yougile-mcp

MCP server to watch and manage YouGile tasks.

An MCP server that exposes YouGile — projects, boards, columns, tasks, and task chat — as tools an agent can call: check on overdue work, create and move tasks, and comment on task chats, all without leaving the chat.

Install

Global install:

npm i -g @skiddgoddamn/yougile-mcp

Register with Claude Code (or any MCP client that reads mcpServers JSON) — no separate install needed, npx fetches it on demand:

{
  "mcpServers": {
    "yougile": { "command": "npx", "args": ["-y", "@skiddgoddamn/yougile-mcp"] }
  }
}

The CLI binary itself is still called yougile-mcp either way.

Auth

The server holds one API key per YouGile company and keeps an active company. There are two ways to get it talking to YouGile:

1. Bring your own key. Create an API key in the YouGile UI (Profile → API keys), then call:

   yg_setup({ apiKey: "<key>" })

   Optionally pass baseUrl if you're on a non-default region/host.

2. Login/password → keys for all companies (recommended). One call fetches (or reuses) a key for every company the login can access and stores them all:

   yg_auth_create_key({ login, password })   // omit companyId → all companies

   Pass companyId to fetch just one. Use yg_auth_companies({ login, password }) first if you only want to preview the list without creating keys.

Using multiple companies. After the fetch-all, switch the active company with yg_company_use({ company: "<id-or-name>" }), or target one per call by passing company on any tool (e.g. yg_tasks_list({ company: "9mice" })). yg_auth_status lists every stored company with masked key previews.

Keys are stored at ~/.yougile-mcp/config.json (override the directory with YOUGILE_MCP_CONFIG_DIR). Login and password are used once per call and are never written to disk.

Tools

18 tools, all prefixed yg_.

Auth

| Tool | Description | |---|---| | yg_auth_status | Show auth status: the active company and every stored company (with masked key previews). | | yg_setup | Store a single YouGile API key (create one in the YouGile UI, or use yg_auth_create_key). Optionally set a custom base URL for self-hosted instances. | | yg_auth_companies | List YouGile companies for a login/password (no keys created). Credentials are used once and NOT stored. | | yg_auth_create_key | Fetch/reuse keys from login/password and store them. Omit companyId to grab keys for all companies at once. Credentials are used once and NOT stored. | | yg_company_use | Switch the active company for later calls (by id or name). Or pass company on any tool to target one per call. |

Structure (projects, boards, columns, people)

| Tool | Description | |---|---| | yg_projects_list | List projects. Filter by title; paginate with limit/offset. | | yg_project_create | Create a project. | | yg_boards_list | List boards. Filter by projectId/title. | | yg_board_create | Create a board inside a project. | | yg_columns_list | List columns. Filter by boardId/title. | | yg_column_create | Create a column on a board. | | yg_employees_list | List company employees/users. Filter by email or projectId. Use to resolve assignee ids. |

Read (tasks & chat)

| Tool | Description | |---|---| | yg_tasks_list | List tasks (the workhorse for watching). Server filters: columnId, title, includeDeleted, limit, offset. Client filters applied to the page: assignedTo (user id), completed, archived, deadlineBefore (ms epoch or ISO), changedAfter (ms epoch or ISO, vs task timestamp). | | yg_task_get | Get one task by id (full card). | | yg_task_chat_get | Read the chat/comments of a task (chatId = task id). Useful for watching discussion. |

Write (tasks & chat)

| Tool | Description | |---|---| | yg_task_create | Create a task in a column. | | yg_task_update | Update a task: move (columnId), assign, deadline, complete, archive, edit title/description. Only provided fields change. Pass deadline=null to clear. | | yg_task_comment | Post a comment to a task's chat. |

Task descriptions are HTML

The description field on yg_task_create / yg_task_update is rendered as HTML — not markdown, not plain text. This is the single easiest thing to get wrong: newlines are ignored, so a plain-text description with \n collapses into one unreadable wall of text in the UI, and the API happily accepts it without complaint.

Use <p> paragraphs, <b> / <i>, <ul>/<ol> + <li>, <br>, <a href>:

yg_task_update({
  id: "…",
  description: "<p><b>Goal.</b> Ship it.</p><ul><li>step one</li><li>step two</li></ul>",
})

Reading a task back returns the same HTML, so round-tripping a description is safe.

Chat messages are not HTML. yg_task_comment takes plain text — newlines there work as expected. Don't send HTML to it.

Watching (on-demand)

This server has no push/webhook mechanism — YouGile is watched on-demand, by having an agent call the list tools on a schedule and reason about the results. Two patterns:

1. Overdue-task sweep. A routine (e.g. Claude Code's /schedule or /loop) that runs every 30 minutes:

now = <current time, ms epoch>

for each board you care about:
  columns = yg_columns_list({ boardId })
  for each column:
    overdue = yg_tasks_list({
      columnId: column.id,
      deadlineBefore: now,
      completed: false,
      archived: false,
    })
    if overdue.count > 0: report them (e.g. post a summary message)

2. Change delta since last run. The agent tracks the timestamp of its previous run (e.g. in its own scratch state) and only asks for what changed since then:

lastRunMs = <timestamp saved from previous run>

changed = yg_tasks_list({ columnId, changedAfter: lastRunMs })
// report `changed.content`, then persist `now` as the new lastRunMs for next time

Both patterns compose: run the delta sweep on every tick, and the full overdue sweep less often (e.g. once a day) as a safety net against missed deltas.

Env vars

| Var | Meaning | Default | |---|---|---| | YOUGILE_MCP_CONFIG_DIR | Directory where config.json (stored API key/company/base URL) lives. | ~/.yougile-mcp | | YOUGILE_BASE_URL | YouGile API base URL (for self-hosted/regional instances). | https://ru.yougile.com/api-v2 | | YOUGILE_API_KEY | Fallback API key used if none is stored yet in config.json. | (unset) | | YG_READONLY | true blocks all mutating tools (_create/_update/_comment) — watch-only mode. | false | | YG_CONFIRM | true requires confirm: true on every mutating tool call. | false | | YG_LOG_LEVEL | Log verbosity: DEBUG, INFO, WARNING, ERROR. | INFO | | YG_LOG_BODIES | true logs raw request/response bodies. See Safety below before enabling. | false | | YG_LOG_FILE | If set, also appends log lines to this file (in addition to stderr). | (unset — stderr only) |

Safety

• YG_READONLY=true — watch-only mode. Every tool whose name contains _create, _update, or _comment (i.e. everything that mutates YouGile) is denied before it runs. Auth tools (yg_setup, yg_auth_create_key, etc.) are exempt, since configuring the server isn't a YouGile-data mutation. Use this when you want an agent to report on tasks but never touch them.
• YG_CONFIRM=true — confirmation mode. Mutating tools return a confirm_required payload describing the call instead of executing it; re-issue the same call with confirm: true to actually run it. Useful for human-in-the-loop review before an agent creates/updates/comments.
• Both can be combined with normal MCP client behavior (READONLY wins — a blocked call never reaches the CONFIRM check).

Security note (important): YG_LOG_BODIES=true logs raw request/response bodies to stderr and/or YG_LOG_FILE. This includes login and password on yg_auth_companies/yg_auth_create_key calls, and the full API key in yg_auth_create_key's response. Leave it off (the default) except for local debugging on your own machine, and never enable it anywhere logs are shared, aggregated, or shipped off-box.

Dev

npm install
npm test
npm run build

Caveats

• Some YouGile GET query-param and task-field shapes are still being finalized against the live API. In particular, color is typed as an integer (1–16) on yg_column_create but as a free-form string on yg_task_create — this matches the current live API behavior observed during development but may need reconciling if YouGile's docs/behavior change.
• List tools (yg_projects_list, yg_boards_list, yg_columns_list, yg_employees_list, yg_tasks_list, yg_task_chat_get) take limit/offset for pagination — YouGile caps pages at roughly 50 items, so boards/projects with more items than that need multiple paged calls to see everything.