clickup-mcp-read

A strictly read-only ClickUp MCP server. It answers questions about a workspace — including a whole nested subtask tree, or a task's whole activity history, in one call — and it cannot change anything.

This is clickup-mcp-full with every write path removed. Like that server, it wraps @twofeetup/clickup-mcp rather than forking it, so upstream fixes arrive with a dependency bump.

Use it for agents that should analyse, report on, or plan against ClickUp — standups, audits, roadmap questions, "what changed last week" — without any chance of a stray tool call editing a task.

What it cannot do

Refused outright, at three independent layers: create, update, delete, move or duplicate a task; create, update or delete a list or folder; post a comment; start, stop, add or delete a time entry; create, rename or delete a tag, or add one to a task; upload an attachment; create or edit a document.

Related MCP server: ClickUp MCP

Why this is a separate server rather than a flag

Upstream consolidated nineteen tools into a handful of multi-action ones, so the read/write line does not fall between tools — it falls inside them. task_comments both reads comments and posts them. task_time_tracking both reports time and starts timers. operate_tags both lists tags and deletes them. A tool allowlist cannot express "reads only"; the unit that has to be filtered is the (tool, action) pair, and that filtering has to live somewhere the calling agent cannot reach.

Three layers hold the line, so no single mistake opens a write:

1. The child never registers the write tools. The wrapped server is started with ENABLED_TOOLS pinned to the read-capable set, so manage_task and friends have no handler at all.

2. Every call is checked here first. A tools/call is matched against the tool allowlist and the per-tool action allowlist before it is forwarded — so a client that names a tool it was never offered is still refused.

3. The advertised schema is pruned. tools/list drops the write tools, strips write actions out of each surviving action enum, and removes the parameters that exist only to carry a write. An agent is never shown an affordance it would then be denied.

The two tools implemented in this server reach ClickUp through a single helper that hardcodes GET and takes a path, not a method, so they cannot become writes either.

This is not a substitute for a read-only token. ClickUp issues one personal token with the full rights of the user who created it; anything else holding that token can still write. This bounds what this server will do with it. For a hard guarantee, create the token under a view-only ClickUp account and use it here.

Why the subtask tree

Upstream's only route to subtasks is search_tasks with include_subtasks, which calls GET /task/{id}?subtasks=true and returns full task objects for the direct children only. On a task with fifty subtasks nested several levels deep that is both incomplete and ruinous for an agent's context window. The alternative, one request per node, is worse.

get_task_tree walks the containing list once instead. ClickUp's GET /list/{id}/task?subtasks=true returns every task in the list along with its parent pointer, so the tree is reassembled locally: two requests total regardless of depth or width, and the output is one compact line per task.

Task tree for 86capt3b: 23 task(s) including the root.
Statuses: in progress: 3, open: 14, complete: 6
List: Q3 Delivery

86capt3b  [in progress]  Migrate billing service  <ivan>
  86captk1  [complete]  Audit current schema  <olena>
  86captk2  [in progress]  Write migration scripts  <ivan>
    86captm7  [open]  Handle partial refunds
    86captm8  [open]  Backfill historical rows
  86captk3  [open]  Cutover plan

Why the activity log

Upstream's task_comments reads comments and nothing else, so "who moved this deadline", "when did it go to in progress", "who added that tag" are simply unanswerable — those events live in ClickUp's task history, which the documented v2 API does not expose at any endpoint.

get_task_activity reads the history the ClickUp web app itself reads (GET /v1/task/{id}/history), merges it with the comments, de-duplicates the comments that appear in both, and renders one chronological log: every status change, due and start date move, assignee, watcher, tag, priority, name and description edit, custom field, list or folder move, attachment, checklist, time estimate and task relationship, with who did it and when.

Activity for 86capt3b (DEV-12): Migrate billing service
7 event(s).
Kinds: Comment: 2, Due date: 1, Tags: 1, Assignee added: 1, Status: 1, Custom field: 1

2026-03-06 12:00  ivan  —  Cutover moved to next week.
2026-03-05 09:00  ivan  —  Due date: 2026-03-10 12:00 → 2026-03-24 12:00
2026-03-04 15:30  olena  —  Tags: blocked, billing
2026-03-04 11:05  olena  —  Assignee added: ivan
2026-03-03 08:00  ivan  —  Status: to do → in progress
2026-03-02 17:45  olena  —  Schema audit done, moving on.
2026-03-01 10:00  ivan  —  Custom field "Sprint": S-14

Narrow it with fields (raw ClickUp field names: status, due_date, assignee_add, tag, custom_field, ...), since (ISO date or millisecond timestamp), limit, include_comments and oldest_first. Timestamps are UTC.

Install

Nothing to clone or build. Point your agent at the package and it is fetched on first launch.

Claude Code

claude mcp add clickup_read \
  --env CLICKUP_API_KEY=pk_your_token \
  --env CLICKUP_TEAM_ID=9012345678 \
  -- npx -y github:breckenreed/clickup-mcp-read

Claude Desktop, Cursor, Windsurf, or any client using mcpServers JSON

{
  "mcpServers": {
    "clickup_read": {
      "command": "npx",
      "args": ["-y", "github:breckenreed/clickup-mcp-read"],
      "env": {
        "CLICKUP_API_KEY": "pk_your_token",
        "CLICKUP_TEAM_ID": "9012345678"
      }
    }
  }
}

Hermes (~/.hermes/config.yaml)

mcp_servers:
  clickup_read:
    command: npx
    args: ["-y", "github:breckenreed/clickup-mcp-read"]
    env:
      CLICKUP_API_KEY: "${CLICKUP_API_KEY}"
      CLICKUP_TEAM_ID: "${CLICKUP_TEAM_ID}"
    connect_timeout: 60
    keepalive_interval: 60
    idle_timeout_seconds: 1800

Global install, if you would rather not resolve from GitHub on every launch:

npm install -g github:breckenreed/clickup-mcp-read

then use clickup-mcp-read as the command with no arguments.

Running this alongside clickup-mcp-full is fine — give them different server names and the agent sees two distinct tool sets.

Credentials

Where the token goes

Refusing to write is only half the problem: the token this server holds is a full-workspace credential either way, so it is kept on a short leash. All of it is asserted by the tests in test/. See SECURITY.md.

• One origin. Every request the native tools make is built as a URL and checked against https://api.clickup.com before the Authorization header is attached. A request to any other origin throws instead of being sent.

• Read-only native path. get_task_tree and get_task_activity share a single helper with the method hardcoded to GET; callers pass a path, never a method or a host.

• A trimmed child environment. The upstream server runs as a child process and receives only the variables it reads (CLICKUP_*, REQUEST_SPACING, LOG_LEVEL, DOCUMENT_*) plus what Node needs to start — not your editor's whole environment, and not NODE_OPTIONS. ENABLED_TOOLS and DISABLED_TOOLS are not passed through either: the child is told the result of the read-only policy, so its own filtering cannot disagree with it.

• A fixed child. The spawned server is resolved from the installed @twofeetup/clickup-mcp. CLICKUP_MCP_ENTRY can only point inside that package, so no environment variable can redirect the credential into other code.

• No listening socket. ENABLE_SSE is forced off and ENABLE_STDIO on, whatever the environment says, so the server is reachable only over the stdio pipe of the process that launched it.

• No file uploads. attach_file_to_task is absent, so a prompt injection an agent reads cannot become a data-egress path.

Tools

Every tool here is read-only. Nine are exposed by default.

With DOCUMENT_SUPPORT=true, two more appear: list_documents, and manage_document_page narrowed to its get and list actions.

Upstream's manage_task, manage_container, attach_file_to_task and manage_document are not present and cannot be enabled.

Options

Raise REQUEST_SPACING on a shared workspace. The default allows about ten requests per second, while ClickUp's per-token limit is roughly 100 per minute on most plans. The limit is counted against the token, not the tool, so an agent that exhausts it also breaks every other integration running under the same token. 700 keeps you under a 100 per minute ceiling.

Notes on behaviour

Refusals are tool errors, not transport errors. A blocked call comes back as a normal tool result with isError and a sentence saying the server is read-only and the write is not possible here. Agents read that and move on; a JSON-RPC error tends to get retried.

Subtasks in another list. The tree is built by walking the list that contains the root task. If your workspace places subtasks in a different list from their parent, those will not appear, and the server falls back to the direct children reported by the task endpoint. Open an issue if you hit this and it matters.

Argument spellings are forgiving. get_task_tree and get_task_activity accept task_id, taskid, a bare id or task wherever the schema says taskId, and the same folding applies to every other argument (maxDepth for max_depth, includeComments for include_comments). Values are coerced to the declared type, so "true", "15" and "status,due_date" work where a boolean, a number and an array are expected. Smaller models get these wrong constantly, and the failures were silent rather than loud: an unread taskId surfaced as "taskId is required", and include_comments: "false" is a non-empty string, so it read as true. The alias used is logged to stderr. This leniency covers those two tools only — the read-only policy gate is not folded or coerced, so a mis-spelled action on a proxied tool is still refused rather than guessed at.

The activity endpoint is undocumented. GET /v1/task/{id}/history is what the ClickUp web app calls, not part of the published v2 API: a personal token can read it today, but ClickUp does not promise that, and some plans or tokens get a 403. That failure is not fatal — get_task_activity then returns the comments plus a line saying the system events were unavailable, so the tool never simply breaks. It pages up to ten pages of history and ten of comments, spaced by REQUEST_SPACING.

search_tasks descriptions. The upstream description ("Works 3 ways") leads smaller models to put a plain id like 86capt3b into customTaskId, which is only for prefixed ids like DEV-123. Such a call falls through to the workspace-search branch and fails with "At least one filter parameter is required", an error that names the wrong problem, after which the model tends to invent filters instead of fixing the field. This server replaces that description with the single rule the model actually needs.

Running inside Docker with a bind-mounted home. If your agent launches MCP servers with HOME pointing at a bind mount, npx rebuilds its package cache across that mount on every connect, which can take minutes and time out. Install globally inside the image instead and point command: at the binary.

Every tool is annotated read-only. All eleven declare readOnlyHint: true, destructiveHint: false, idempotentHint: true and openWorldHint: true, so a host can decide what to warn about before it calls anything, and directories that require the four hints (OpenAI's among them) accept the set. On this server they are all the same claim, because a tool that could make any other claim is not exposed at all — that is the annotation this build exists to be able to make honestly.

Development

There is nothing to build. The tests run on the standard library alone:

npm test

test/format.test.mjs and test/tools.test.mjs cover the tree assembly, the activity rendering, the argument normalisation, and the read-only policy as plain functions — every write tool and every write action, checked by name. test/server.test.mjs spawns the server the way a host does and drives it over stdio: the handshake, the tool list, the pruned schemas, the refusals, the guard on the entry override, and the fact that ENABLED_TOOLS cannot put a write tool back. None of them touch the network or need a ClickUp workspace.

Troubleshooting

Check that the server starts and lists its tools:

CLICKUP_API_KEY=pk_... CLICKUP_TEAM_ID=... npx -y github:breckenreed/clickup-mcp-read --help

Missing required environment means the variables did not reach the process: most clients require them in the server's own env block, not your shell.

A 401 from any tool means the token is wrong or was revoked. A 429 means you are hitting the rate limit, so raise REQUEST_SPACING.

License

MIT, like the upstream server it wraps. @twofeetup/clickup-mcp is the MIT-licensed community continuation of the pre-paid tree of @taazkareem/clickup-mcp-server.