weeek-mcp

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

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:

config.json

{
  "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).

Read tool	Returns
`ping`	`pong: <msg>` — transport health check, no API call, no token
`weeek_get_me`	the authenticated user (`id`, `email`, `name`) — confirms the token
`weeek_list_projects`	every project visible to the token
`weeek_get_project`	a single project by id, including its `description`
`weeek_list_tasks`	one page of tasks (filters + offset/`per_page` pagination)
`weeek_get_task`	a single task by id, with multi-assignee fields
`weeek_list_members`	every workspace member
`weeek_list_tags`	every tag
`weeek_list_boards`	every board in a project
`weeek_list_board_columns`	every column of a board, in sort order

Write tool (`READ_ONLY=false`)	Does
`weeek_complete_task`	flips the completion flag; `completed: false` re-opens
`weeek_move_task`	moves a task to a board column (a column is a status)
`weeek_create_task`	files a new task and returns it with its new id
`weeek_update_task`	edits title / priority / type / due date
`weeek_set_task_mr_link`	records a merge/pull-request URL in a custom field

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.

json

"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:

json

"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

Tool	Changes	Undone by	`destructiveHint`	`idempotentHint`
`weeek_complete_task`	one completion flag	re-firing with `completed: false`	`false`	`true`
`weeek_set_task_mr_link`	one custom field's value	re-setting it	`false`	`true`
`weeek_move_task`	the task's board column (and board)	moving it back — if you know where it was	`true`	`false`
`weeek_update_task`	title / priority / type / due date	re-setting each field — if you know the old value	`true`	`false`
`weeek_create_task`	files a new task	deleting it, which this server cannot do	`true`	`false`

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.

Variable	Required	Default	Purpose
`WEEEK_ACCESS_TOKEN`	yes	—	Personal Weeek API token (≥ 20 chars; placeholders and whitespace-padded values are rejected).
`WEEEK_BASE_URL`	no	`https://api.weeek.net/public/v1`	Base URL for the Weeek HTTP client. Override for self-hosted proxies.
`WEEEK_TIMEOUT_MS`	no	`30000`	Per-request timeout (ms). Positive integer.
`READ_ONLY`	no	`true`	Hide write tools. When `true`, any tool whose `readOnlyHint !== true` is not registered. Accepts `true`/`false`/`1`/`0`.
`ENABLED_TOOLS`	no	(unset = all)	Comma-separated allowlist of tool names, still intersected with `READ_ONLY`. Unknown names WARN; an empty result aborts startup.
`MAX_RESPONSE_CHARS`	no	`65536`	Byte budget per response; over-budget payloads are clipped and flagged `truncated: true`. Min `1024`, max `1000000`.
`LOG_LEVEL`	no	`info`	Logger threshold: `debug`, `info`, `warn`, `error`. Unknown values fall back to `info`.

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

Symptom	Likely cause	Fix
Server doesn't appear in the client	`command` points at a `node` the client cannot find, or `dist/index.js` is missing/non-executable	Run `npm run build`; confirm `ls -la dist/index.js` shows `0755`. Use the absolute path from `which node` (see NVM note below).
`MCP server failed to start` immediately	Same as above, plus `node_modules` missing	Run `npm install && npm run build` from the repo root.
`invalid env: WEEEK_ACCESS_TOKEN: ...` on stderr	Token contains whitespace/control chars, or is the placeholder	Generate a real token at https://app.weeek.net/ws/_/settings/apps/api and paste it without surrounding spaces or newlines.
`invalid env: WEEEK_BASE_URL: ...`	URL uses a non-`http(s)` scheme or contains `user:pass@`	Use plain `https://api.weeek.net/public/v1`; route credentials through `WEEEK_ACCESS_TOKEN`.
`EACCES` launching `dist/index.js`	`postbuild` chmod skipped	`chmod +x dist/index.js`.
`npm start` works but the client fails	The client launches under a different `PATH` than your shell	See the NVM workaround below.

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:

config.json

{ "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.

Code

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.