weeek-mcp

Local, read-only-by-default MCP server for Weeek — with opt-in write tools.

Русская версия README

weeek-mcp connects AI clients (Claude Desktop, Claude Code, Cursor, MCP Inspector) to your Weeek workspace over stdio. It is read-only by default — a default install can list projects, tasks, boards, members and tags but change nothing — and exposes five write tools only when you opt in with READ_ONLY=false. Runs on Node ≥ 20; install with npx, no clone or build required.

Why this one

• On npm. npx -y weeek-mcp works today — no clone, no build, no absolute paths.
• Read-only by default, with composable gates. Writes are simply not registered unless you opt in; ENABLED_TOOLS whitelists a subset and MAX_RESPONSE_CHARS caps every payload. Server-side, not client convention.
• Bilingual. Full EN ↔ RU documentation parity.
• Granular error model. Nine distinct error codes with agent-readable messages, so a model knows when to retry versus give up without parsing prose.

Quickstart

The recommended install path is npx — no clone, no build. Drop examples/claude_desktop.mcp.json into your MCP client config, replace YOUR_WEEEK_TOKEN_HERE with a real token from https://app.weeek.net/ws/_/settings/apps/api, and restart the client:

{
  "mcpServers": {
    "weeek": {
      "command": "npx",
      "args": ["-y", "weeek-mcp"],
      "env": {
        "WEEEK_ACCESS_TOKEN": "YOUR_WEEEK_TOKEN_HERE"
      }
    }
  }
}

npx downloads weeek-mcp on first launch and caches it. Cursor and Cline use the same mcpServers shape — see examples/cursor.mcp.json and examples/cline.mcp.json. Other env vars have safe defaults; override only what you need (see Configuration). If npx cannot find node (typical with nvm), see Troubleshooting; for a zero-dependency smoke test see docs/smoke.md.

examples/ lives on GitHub only — the npm tarball ships dist/ + README.md + README.ru.md + LICENSE.

Tools

Ten read tools are exposed by default. All fifteen appear only under READ_ONLY=false (see Enabling write tools).

Full field-level reference (inputs, outputs, edge cases, truncation, multi-assignee) → docs/tools.md.

Enabling write tools

The default install cannot change anything in your workspace. All five mutating tools are hidden behind READ_ONLY (default true) — not registered, so they never appear in tools/list. Setting READ_ONLY=false takes tools/list from ten tools to fifteen and lets the agent create, edit, move and complete tasks in the workspace the token can reach. There is no server-side confirmation step — annotations are a hint an MCP client is free to ignore. Point the token at a workspace whose contents you are willing to see changed.

"env": {
  "WEEEK_ACCESS_TOKEN": "YOUR_WEEEK_TOKEN_HERE",
  "READ_ONLY": "false"
}

Start with one tool, not five. READ_ONLY=false intersected with ENABLED_TOOLS gives you writes on, but only the one you asked for:

"env": {
  "WEEEK_ACCESS_TOKEN": "YOUR_WEEEK_TOKEN_HERE",
  "READ_ONLY": "false",
  "ENABLED_TOOLS": "weeek_complete_task"
}

READ_ONLY is the outer gate: naming a write tool in ENABLED_TOOLS does not by itself opt into writes. The allowlist is not additive, so list the read tools you need alongside it — examples/claude_desktop.write.mcp.json is a ready-to-edit config that does exactly that.

What each write tool can and cannot do

The three true rows are marked "worth a human confirm" because the agent never saw the old value and cannot put it back; weeek_create_task is the one to watch — its effect cannot be undone through this server, and a retried create files a second task. weeek_set_task_mr_link resolves its custom field by name unless you pass custom_field_id / custom_field_name — the matched names and ambiguity rules are in docs/tools.md.

Configuration

Read from the environment at startup and validated with zod; invalid values abort startup on stderr with a non-zero exit code. The server never reads a .env file itself — pass variables through your MCP client's env block or your shell.

Both gates run server-side: a hidden tool is not registered, so an agent cannot call it. READ_ONLY is load-bearing — leave it at the default unless you intend an agent to change your workspace. See .env.example for a copy-pasteable template.

Troubleshooting

{ "command": "/Users/<you>/.nvm/versions/node/v20.18.0/bin/npx", "args": ["-y", "weeek-mcp"] }