clickup-custom-mcp

A stdio MCP server that talks to the ClickUp REST API v2 directly.

It exists because ClickUp's hosted MCP (mcp.clickup.com) caps a Free workspace at 50 calls per 24 hours and refuses personal API tokens, while the same account's REST API allows 100 requests per minute. This server trades a daily ceiling for a per-minute one, and keeps the token on your machine instead of in a hosted integration.

Requirements

• Node 20+ (see engines in package.json)

• A ClickUp personal API token

Related MCP server: clickup-mcp

Setup

npm install
npm run build

Generate a token in ClickUp: avatar → Settings → Apps → API Token → Generate.

Copy .env.example to .env at the repo root (.env is gitignored) and fill in the token:

cp .env.example .env

The server loads that file itself via process.loadEnvFile, so the token never has to be written into Claude Code's config — where claude mcp add -e would store it in plaintext. Anything already present in the environment wins over .env, and if the file is missing (or the Node build has no loadEnvFile) the server simply falls back to plain environment variables.

Environment variables

Register with Claude Code

claude mcp add clickup-custom-mcp -- node /absolute/path/to/clickup-custom-mcp/dist/index.js

No -e CLICKUP_API_TOKEN=... is needed — the .env file covers it.

Register with Claude Desktop

Add an entry under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json, then fully quit and reopen the app:

"clickup-custom-mcp": {
  "command": "/absolute/path/to/node",
  "args": ["/absolute/path/to/clickup-custom-mcp/dist/index.js"]
}

Use the absolute path from which node: the app does not load your shell profile, so a bare node (especially an nvm install) is not on its PATH. Behind a TLS-intercepting proxy, add "env": { "NODE_EXTRA_CA_CERTS": "/path/to/root.pem" }. It must be set here because Node reads it only at startup, before .env is loaded.

Run it standalone with npm start. stdout is the JSON-RPC channel, so every diagnostic (including a per-request log line with ClickUp's remaining quota) goes to stderr.

Tools

Seven coarse tools, each shaped around a job rather than an endpoint. The fan-out lives in the server, not in the model: one get_my_work call costs 2 HTTP requests where walking space → folder → list → task from the model side costs thirty.

Every tool reports how many HTTP requests it spent, and any result that hit the page cap says Truncated rather than quietly returning a short list.

Design notes

• Rate gate (src/clickup.ts) — a sliding 60-second window plus a concurrency cap of 4. A fixed-interval refill would let a burst of 90 fire in the first second and then stall for 59; tracking actual send times spreads the same budget.

• 429 handling — backoff is driven by ClickUp's own X-RateLimit-Reset header, retried up to 3 times. The client also coasts down when X-RateLimit-Remaining drops to 2 rather than taking a 429 mid-fan-out.

• Structure cache — hierarchy, custom fields and member lists are memoised for 15 minutes. Task data is deliberately never cached.

• Compact output (src/format.ts) — raw ClickUp task JSON runs 2–4KB each. Every tool projects down to the fields a person actually reads and renders markdown instead of JSON.

Layout

src/index.ts    entrypoint: env loading, client + server wiring, stdio transport
src/clickup.ts  REST client: rate gate, retry/backoff, TTL cache, task pagination
src/tools.ts    the six MCP tool definitions and their fan-out
src/format.ts   task projection and markdown rendering