io.github.YOLKINS/weeek-mcp

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

NVM workaround — spawn npx ENOENT / spawn node ENOENT

Claude Desktop and Cursor launch their MCP subprocess under a non-interactive shell that does not source ~/.nvm/nvm.sh, so a bare "command": "npx" silently fails when Node is installed via nvm. Either hard-code an absolute path — run which npx and paste the result as command (update it whenever you switch nvm version); the package is still downloaded and cached on first run:

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

— or point command at a small wrapper script that sources ~/.nvm/nvm.sh before exec npx "$@", which survives nvm version changes.

Errors

Every Weeek tool fails the same way: isError: true with a single-line <tool> failed (<weeek_code>): <one English sentence>. The weeek_<code> token is the stable, machine-greppable contract; the sentence guides self-correction. Nine codes cover unauthorized / forbidden / not-found / validation / rate-limit / server / network / timeout / invalid-response, each with retry guidance.

weeek_get_task failed (weeek_not_found): Weeek returned 404 for this resource. Verify the id exists in the configured workspace and was not deleted.
weeek_list_tasks failed (weeek_rate_limited): Weeek rate-limited the request (HTTP 429). Retry after a brief delay or reduce the call frequency.

Full table with retry semantics → docs/errors.md.

Contributing · Security · License

• Contributing — issues and feature requests are welcome; pull requests are by prior agreement (this repo runs a strictly linear increment process). See CONTRIBUTING.md.
• Security — found a way to leak the token or a byte on stdout? Do not open a public issue; see SECURITY.md for the private channel and threat model.
• License — MIT.
• For AI coding agents — the entry-point contract (invariants, pinned deps, pre-merge checklist) lives in CLAUDE.md.

CONTRIBUTING.md, SECURITY.md and CLAUDE.md live on GitHub only — like examples/, they are not in the npm tarball. LICENSE is the exception: it ships inside the package.