What is clickup-mcp CLAUDE.md?

Development instructions for ClickUp MCP, a connector that lets an AI assistant work with ClickUp, a task and project-management service. They cover API limits, short-term caching, building, tests, and command-line checks.

Use them when developing or testing ClickUp API operations, especially task and workspace lookups, through this MCP connector.

They reduce failed requests and inconsistent results while keeping changes validated against the project’s expected workflow.

How sebastienheyd/clickup-mcp configures Claude Code

Reuse

Borrowing it

Nothing to install: this file belongs to sebastienheyd/clickup-mcp. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/sebastienheyd/clickup-mcp/main/CLAUDE.md

Clone the repo

git clone --depth 1 https://github.com/sebastienheyd/clickup-mcp

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/sebastienheyd/clickup-mcp/claude-md/github.svg)](https://agentmods.dev/instructions/sebastienheyd/clickup-mcp/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/sebastienheyd/clickup-mcp/claude-md"><img src="https://agentmods.dev/badge/instructions/sebastienheyd/clickup-mcp/claude-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/instructions/sebastienheyd/clickup-mcp/claude-md"><img src="https://agentmods.dev/badge/instructions/sebastienheyd/clickup-mcp/claude-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 1,420 This file is loaded in full into every session.

When invoked 1,420 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.01420	$0.01420
Opus 5.5	$0.00568	$0.00568
Sonnet 5.5	$0.00284	$0.00284
Haiku 4.5	$0.00142	$0.00142

Measured 1mo ago against content hash f8732e43dcce, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

clickup-mcp CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 26 lines

How it starts

The opening of the file, as written. The whole thing — 26 lines — stays where its author put it; the contents beside it link to each section on GitHub.

ClickUp api documentation is available here: https://developer.clickup.com/reference/gettasks
Think about api limits. ClickUp allows 100 api calls per minute per user. A typical workflow must not exceed that.
Implement caching by using a global variable and setting it to null after a setTimeout with GLOBAL_REFRESH_INTERVAL. The ClickUp Api limit resets after a minute, so we usually don't need to cache longer than a minute.
Cache promises, not results, to prevent race conditions when multiple concurrent calls happen before the first completes (see getAllTeamMembers, getCurrentUser, getTaskSearchIndex, getSpaceSearchIndex patterns).
Use "npm run build" to compile the typescript for validation.
Use "npm run cli" to test mcp calls.
CLI syntax: npm run cli key=value key2=""quoted string"" arrayKey='["item1","item2"]' objectKey='{"field":"value"}'
For multi-line values (markdown descriptions/comments) call "npx ts-node src/cli.ts" directly - "npm run cli" re-splits arguments through a second shell and loses them.
Use "npm run test" to run tests.
Use "npm run smoke" after a build to check the MCP protocol layer (initialize, tools/list, schemas) - "npm run cli" calls tool callbacks directly and never exercises stdio transport or tool registration. Add "-- <task_id> <image.png>" to also post a real comment with an image.
Tests need src/tests/setup.ts preloaded (see the test script): it points global fetch at the npm undici so MockAgent can intercept. Node's built-in fetch uses Node's own bundled undici, which MockAgent cannot reach.
Use console.error to prevent writing log messages to stdout.
MCPB manifest.json spec is at https://github.com/anthropics/mcpb/blob/main/README.md - update tools section when adding new MCP tools.
Update the CHANGELOG.md when changing or implementing a new feature.
Backwards compatibility does not matter, an LLM will understand new parameters.
Mention ID's, not just names, when outputting references. for example "User: Username (user_id: 12345)"
PUT /api/v2/comment/{id} accepts the same undocumented rich comment fragment array as comment creation (the API reference only lists comment_text, and assignee/resolved are not actually required). Sending comment and comment_text together appends the latter. There is no GET /comment/{id}, so editComment reads the task's comment list to check author and age. That list returns only the 25 newest comments per page - start_date is not a real parameter and is ignored; older pages need start + start_id of the previous page's last comment.
Comment edits and images (verified live): PUT /comment/{id} only accepts image fragments of images ALREADY in that comment, with their real attachment id (<uuid><ext>, the uuid being the CDN path segment before the filename) - any other attachment (fresh upload, description image, another comment's image) is refused with 401 ACCESS_610, a wrong id with 404 ACCESS_028. editComment therefore reuses the stored fragment objects and rejects other images before uploading. POST (addComment) accepts new and existing attachments.
Image writing lives in src/shared/attachments.ts: markdown image sources are uploaded to the task, then comments get a type: "image" fragment carrying the whole attachment object (a bare URL string renders as an empty tile), while descriptions only need the markdown URL swapped. Attachments always belong to a task - doc pages cannot have them. Reading renders images back as ![alt](url) markdown (clickup-text.ts toMarkdownImage) so a comment read via getTaskById can be fed straight back into editComment without losing them - keep that read/write symmetry intact.
Commit messages and CHANGELOG entries must always be written in English.
ClickUp comments cannot render tables (no table fragment exists; unknown attributes are stored but render as plain text) - convertMarkdownToClickUpBlocks turns tables into aligned pipe tables inside a code block. Quill block attributes apply per line: every code-block line needs its own \n fragment with the code-block attribute, otherwise only the last line renders as code. Comments DO support strike/underline/color attributes even though the comment UI barely exposes them.
ClickUp comments have no paragraph margins: a paragraph break is an extra empty \n fragment (Enter twice in the UI). convertMarkdownToClickUpBlocks inserts one between adjacent paragraphs/lists, and between two adjacent code blocks/tables (Quill fuses consecutive code-block lines into one block, so without it a command and its output, or a code block and a table, collapse into a single block) - headings, code blocks next to text, and blockquotes already render with their own spacing.
Task dependencies (verified live): the task payload has no blocking/waiting_on arrays - both directions are records { task_id, depends_on } of one flat dependencies array, with the task on either side (task_id = this task means it waits on depends_on). linked_tasks records have task_id/link_id. Due/start dates lose their time of day unless due_date_time/start_date_time: true is sent (ClickUp stores the 04:00 all-day placeholder instead). The task payload's priority.priority is the priority NAME ("low"), not a number.
Clearing task fields via PUT /task/{id} (undocumented, verified live): null clears due_date, start_date and points, but time_estimate: null is accepted and silently ignored - only 0 clears it. points must be a value of the points scale configured in the workspace, which differs between workspaces - never hardcode or validate a scale locally, let ClickUp reject off-scale values (ITEM_222 not a valid points selection). assignees on update is { add, rem } and both keys are required.
Time entries (/team/{team_id}/time_entries/{id}, verified live): PUT does not require tags despite the API reference. duration alone works (end is recomputed), start+end alone works (duration is recomputed), but start alone moves the start and leaves end in place - always send start, end and duration together. DELETE answers {} and GET on a deleted or unknown id answers 200 {"data": null}, not a 404.

Read the full file on GitHub · 26 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

1mo ago Changed · +2 lines · +250 tokens per session f8732e43dcce
1mo ago Changed · +4 lines · +436 tokens per session d7d49c1972ee
2mo ago First seen · 20 lines · 734 tokens per session scan A dfcb0b501c9b

Subscribe to this mod's changes

clickup-mcp CLAUDE.md is an instructions file published in the GitHub repository sebastienheyd/clickup-mcp (0 stars, last pushed 1mo ago), licensed MIT. It adds 1,420 tokens to every session, about $0.0057 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Project management

clickup-mcp CLAUDE.md next to 6 instructions from other repositories
Mod	Type	Stars	Last push	Licence	Scan	Tokens	Works with
clickup-mcp CLAUDE.mdsebastienheyd/clickup-mcp	Instructions file	0	1mo ago	MIT	A	1,420	Claude Code
vscode buildNext.instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	9,719	GitHub Copilot
next.js AGENTS.mdvercel/next.js	Instructions file	143k	yesterday	MIT	A	7,461	Codex, OpenCode
langchain AGENTS.mdlangchain-ai/langchain	Instructions file	149k	yesterday	MIT	A	4,680	Codex, OpenCode
vscode oss-third-party-notices.instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	5,516	GitHub Copilot
vscode copilot-instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	3,093	GitHub Copilot
deepseek-harness AGENTS.mddeepseek-ai/deepseek-harness	Instructions file	274k	2d ago	MIT	A	4,313	Codex, OpenCode

clickup-mcp: Instructions file for Claude Code