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.

Related MCP server: YouTrack MCP

Auth

There are two ways to get the server talking to your YouGile company:

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 → key. Two-step flow that never persists your credentials:

   yg_auth_companies({ login, password })       // lists companies you belong to
   yg_auth_create_key({ login, password, companyId })  // creates/reuses a key, stores it

Either path stores the resulting API key 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. Check current status any time with yg_auth_status.

Tools

17 tools, all prefixed yg_.

Auth

Structure (projects, boards, columns, people)

Read (tasks & chat)

Write (tasks & chat)

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

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.