clickup-mcp: Instructions file for Claude Code

CLAUDE.md — ClickUp MCP Server

Notes for working on this codebase.

What this is

A multi-user MCP server for ClickUp. Pattern B (Python + FastMCP + OAuth delegation) from ../General.Claude.md, extended with the per-identity governance layer from ../CW Manage 3/src/middleware/.

Reference implementations, and what each contributes:

• ../Whoop/ — OAuth delegation mechanics, client shape, transform.py, Docker layout. Single-user; do not copy its token handling.
• ../CW Manage 3/src/middleware/ — genuinely multi-user. policy-gate.ts, audit-capture.ts, rate-limit.ts, identity-resolver.ts are the originals for this server's policy.py, audit.py, rate_limit.py, context.py. Note that General.Claude.md files it under "Pattern A: TypeScript + API Key", which badly undersells it.

The one rule

Never introduce process-global state keyed on anything but grant id.

The whole design turns on context.current_client() resolving the calling user's token per request. Three things must stay namespaced by grant:

• ClickUpClient._caches — an un-namespaced cache serves user A's tasks to user B
• rate_limit._buckets
• everything written to audit_log

tests/test_isolation.py is the gate. Run it before and after any change to store.py, client.py, context.py, or oauth_provider.py.

ClickUp API facts that trip people up

• The v3 spec is ~20% of the API. Chat, Docs, audit logs, and a few strays. Tasks/Lists/Spaces/Folders/time tracking/comments/custom fields are v2 only. Both specs are vendored: ClickUp_PUBLIC_API_V3.yaml (35 ops) and clickup-api-v2-reference.json (137 ops).
• No PKCE, no scopes on ClickUp's side. Do not add them back to oauth_provider.authorize().
• No refresh token, tokens never expire. There is deliberately no refresh path in client.py. A 401 with an OAUTH_* ECODE means revoked → prompt re-auth. A 401 with any other code is a permissions error and must NOT be reported as a dead token (_looks_like_bad_token draws that line).
• Rate limit is per token = per user. 100/min on most plans.
• The v2 spec has wrong types — time_spent/time_estimate are declared string|null but come back as integers. Don't codegen models from it.
• "Team" means Workspace in the v2 API. Tools expose it as workspace_id; paths use team_id. _common.client_and_workspace() does the mapping and fills in the default when the user has exactly one Workspace.
• User Groups are also called "Teams" in ClickUp's UI. Different thing. See tools/groups.py.
• Folderless Lists still carry a folder object — a placeholder {"name": "hidden", "hidden": true}, not an omission. Read it naively and you report a folder named "hidden"; that was 54 of the first 100 live tasks. Use transform._folder_name(), which checks the flag.
• A task's space has only an id, no name — hence the space_id key.
• Task payloads are ~11 KB each. One 100-task page measured 1.12 MB raw versus 41 KB summarized. raw=True on a list query is a context-window hazard; say so when a tool offers it.