clickup-full-mcp
Provides full access to the ClickUp API (v2 and v3), enabling management of tasks, subtasks, lists, folders, spaces, comments, checklists, custom fields, tags, dependencies, time tracking, goals, guests, users, user groups, templates, views, webhooks, workspaces, OAuth, Chat, Docs, Attachments, ACLs, and Audit Logs.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ClickUp MCP Server (clickup-full-mcp)
The entire ClickUp API in 4 tools. A local Model Context Protocol server that lets Claude, Cursor, VS Code Copilot and any other MCP client use all 173 ClickUp API operations (v2 + v3) for about 700 tokens of context instead of ~55,000.
Tasks, subtasks, lists, folders, spaces, comments, checklists, custom fields, tags, dependencies, time tracking, goals, guests, users, user groups, templates, views, webhooks, workspaces and OAuth, plus the v3 Chat, Docs, Attachments, ACLs and Audit Logs APIs. Every tool is generated from ClickUp's official OpenAPI specs, so nothing is hand-picked or missing.
Community project, not affiliated with or endorsed by ClickUp.
Contents
Client setup: Claude Desktop, Claude Code, Cursor, VS Code, others
Common ClickUp operations: examples you can copy
Related MCP server: clickup-mcp-server
Why 4 tools?
Most API-wrapping MCP servers register one tool per endpoint. For ClickUp that means 173 tool schemas loaded into the model's context on every request, before you've typed anything. That's slower, costs more, crowds out your actual conversation, and makes it harder for the model to pick the right tool. Some clients also cap how many tools a server may register.
By default this server exposes just 4 tools that reach the whole API:
Tool | What it does |
| Finds operations by keyword: "create task", "log time", "send chat message"… |
| Returns one operation's full description and JSON input schema, only when it's needed. |
| Calls any of the 173 operations by name. |
| Raw escape hatch for any |
Measured tools/list size (v1.0.0, tokens ≈ characters ÷ 4):
Mode | Tools | Schema size | Context cost |
| 174 | 214 KB | ~55,000 tokens |
| 42 | 61 KB | ~15,600 tokens |
| 4 | 2.6 KB | ~700 tokens (−98.8%) |
A typical meta-mode exchange costs one or two extra small calls, and the model only ever loads the schemas it actually uses:
// 1. Find the operation
clickup_search_operations { "query": "create task" }
// → [{ "name": "create_task", "http": "POST /api/v2/list/{list_id}/task", … }, …]
// 2. (optional) Read its schema
clickup_describe_operation { "name": "create_task" }
// 3. Call it, with the same arguments as the full-mode tool
clickup_call_operation { "name": "create_task", "arguments": { "list_id": "901", "body": { "name": "Ship MCP" } } }Search understands everyday wording: "log time" finds create_time_entry, "find tasks" finds get_tasks, "post message" finds send_chat_message.
Prefer direct tools? Set CLICKUP_TOOL_MODE=full to register one tool per endpoint, and use CLICKUP_TOOLSETS to trim it to the areas you use. Both modes respect CLICKUP_TOOLSETS, CLICKUP_READ_ONLY and CLICKUP_DISABLED_TOOLS.
Features
Complete coverage: 173 operations (138 v2 + 35 v3) with full JSON Schemas for every parameter and request body. See the tool reference.
Token-efficient by default: 4-tool meta mode (~700 tokens), or full mode with per-toolset filtering.
Scoping: read-only mode, toolset filters, and a deny-list for individual tools like
delete_space.Fixes where the spec is wrong: array filters are encoded the way the live API expects (
statuses[]=a,group_ids=a&group_ids=b, JSONcustom_fields), and upload field names match the live API.Built for real use: 429 retries that honour
Retry-After/X-RateLimit-Reset, timeouts, response truncation, file uploads, OAuth tokens, and MCP tool annotations (read-only / destructive hints).Helpful errors: unknown or misplaced arguments are rejected before any HTTP call, with a hint; ClickUp errors include the HTTP status and
ECODE.Local and private: runs on your machine over stdio. Your token only goes to the ClickUp API.
Always current: a weekly CI job pulls ClickUp's latest OpenAPI specs and opens a PR when they change.
Quick start
Requirements: Node.js 20+.
Get a ClickUp API token: ClickUp → your avatar → Settings → Apps → API Token (starts with
pk_). OAuth access tokens also work.Add the server to your MCP client (see Client setup). The quickest way runs it straight from GitHub:
npx -y clickup-full-mcpNo install step:
npxfetches the npm package on first run. The server is also listed in the official MCP Registry asio.github.KelvinCampelo/clickup-full-mcp.Ask your assistant something like:
"List the open tasks assigned to me in the Sprint 42 list."
"Create a task in Backlog called 'Ship MCP', priority high, due Friday, with a QA checklist."
"Move every task tagged
bugin Inbox to Triage and comment 'moved by triage bot'.""Log 1h30 on task
86abc123for today with the note 'code review'.""How many hours did I track this week, per task?"
"Summarize this week's messages in the #engineering chat channel."
"Create a Doc page 'Release notes v1.2' from the tasks closed this sprint."
For a first run, addCLICKUP_READ_ONLY=true. Only GET endpoints are exposed, so nothing can be changed.
Alternative: run from a local clone
git clone https://github.com/KelvinCampelo/clickup-full-mcp.git
cd clickup-full-mcp
npm install # also builds dist/
npm test # optional: end-to-end tests against a mock ClickUpThen use "command": "node" and "args": ["/ABSOLUTE/PATH/clickup-full-mcp/dist/index.js"] in the client configs below.
Client setup
The server starts in 4-tool meta mode. Add "CLICKUP_TOOL_MODE": "full" to env if you'd rather have one tool per endpoint. CLICKUP_WORKSPACE_ID is optional but saves the model a lookup on every call.
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"clickup": {
"command": "npx",
"args": ["-y", "clickup-full-mcp"],
"env": {
"CLICKUP_API_TOKEN": "pk_xxx",
"CLICKUP_WORKSPACE_ID": "1234567"
}
}
}
}claude mcp add clickup --scope user \
-e CLICKUP_API_TOKEN=pk_xxx -e CLICKUP_WORKSPACE_ID=1234567 \
-- npx -y clickup-full-mcp~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"clickup": {
"command": "npx",
"args": ["-y", "clickup-full-mcp"],
"env": { "CLICKUP_API_TOKEN": "pk_xxx", "CLICKUP_WORKSPACE_ID": "1234567" }
}
}
}.vscode/mcp.json. VS Code prompts for the token and stores it securely:
{
"inputs": [{ "type": "promptString", "id": "clickup-token", "description": "ClickUp API token", "password": true }],
"servers": {
"clickup": {
"type": "stdio",
"command": "npx",
"args": ["-y", "clickup-full-mcp"],
"env": { "CLICKUP_API_TOKEN": "${input:clickup-token}" }
}
}
}Run npx -y clickup-full-mcp (or node dist/index.js from a clone) as a stdio MCP server with the environment variables below. This works with any client or agent SDK that can launch local stdio servers.
Prefer containers? Build the image from a clone and run it over stdio:
docker build -t clickup-full-mcp .
docker run -i --rm -e CLICKUP_API_TOKEN=pk_xxx clickup-full-mcpCommon ClickUp operations
Each row is one operation. In meta mode (the default), pass the arguments to clickup_call_operation as { "name": "<tool>", "arguments": { … } }; in full mode, call the tool directly. The examples assume CLICKUP_WORKSPACE_ID is set, so team_id / workspace_id can be left out. Dates are Unix timestamps in milliseconds. Every tool's full argument list is in the tool reference.
Tasks
Goal | Tool | Arguments |
Get tasks in a list, filtered |
| |
Search tasks across the workspace |
| |
Get one task with its subtasks |
| |
Create a task |
| |
Create a subtask |
| |
Change status, assignees, priority |
| |
Move a task to another list |
| |
Delete a task |
|
Comments, checklists, tags, custom fields
Goal | Tool | Arguments |
Comment on a task |
| |
Read a task's comments |
| |
Add a checklist |
| |
Add a checklist item |
| |
Tag a task |
| |
List a list's custom fields |
| |
Set a custom field value |
|
Time tracking
Goal | Tool | Arguments |
Start a timer |
| |
Stop the running timer |
| |
Log time after the fact |
| |
Timesheet for a date range |
|
Workspace structure, Docs and Chat
Goal | Tool | Arguments |
List workspaces (find your ID) |
| |
Browse spaces → folders → lists |
| |
Lists that aren't in a folder |
| |
List Docs / read a Doc's pages |
| |
Write a Doc page in Markdown |
| |
Find a Chat channel |
| |
Post a Chat message |
| |
Anything not covered by a typed tool |
|
|
Configuration
All configuration is through environment variables. See .env.example.
Variable | Default | Purpose |
| (none) | Personal token ( |
| (none) | Default Workspace (team) ID. Auto-fills |
|
|
|
| all | Comma list of toolsets to expose (works in both modes). |
|
| Only expose GET operations; |
| (none) | Comma list of operation names to hide, e.g. |
|
| Expose |
| (none) | Comma list of folders that |
|
| Truncate very large responses. |
|
| Request timeout and 429 retries. |
|
| Override for testing or proxies. The token is sent to this host. |
Find your Workspace ID in any ClickUp URL (app.clickup.com/<workspace_id>/…), or ask the assistant to run get_authorized_workspaces.
Toolsets
Each toolset links to its generated reference page with every tool's arguments and body fields (index).
attachments (3) · audit_logs (1) · authorization (2) · chat (19) · comments (11) · custom_fields (6) · custom_task_types (1) · docs (8) · folders (7) · goals (8) · guests (10) · lists (11) · members (2) · privacy_and_access (1) · roles (1) · shared_hierarchy (1) · spaces (5) · tags (6) · task_checklists (6) · task_relationships (4) · tasks (13) · templates (3) · time_tracking (17) · user_groups (4) · users (4) · views (12) · webhooks (4) · workspaces (3)
How tools map to the API
📖 Tool reference: every tool with its HTTP endpoint, arguments and request-body fields, generated from the OpenAPI specs.
Tool names are snake_case versions of the endpoint (
create_task,get_tasks,send_chat_message,get_doc_pages, …).Path and query parameters go at the top level of the arguments.
JSON request bodies go in
body:{ "list_id": "901", "body": { "name": "Ship MCP", "priority": 2, "assignees": [123] } }File uploads (
create_task_attachment,create_attachment): passfile_path(a local file) orfile_base64+file_name.Errors come back as
isErrorresults with the HTTP status and ClickUp'serr/ECODE. Unknown or misplaced arguments are rejected before any HTTP call, with a hint (e.g. "request-body fields go insidebody").Annotations mark GETs as read-only and DELETEs as destructive, so clients can ask for confirmation.
Every tool description ends with its HTTP method and path, e.g.
ClickUp API v2: POST /api/v2/list/{list_id}/task.
OAuth (get_access_token)
For OAuth apps, get_access_token exchanges an authorization code (body: {client_id, client_secret, code}) for an access token. It's sent without an Authorization header. Put the returned access_token in CLICKUP_API_TOKEN; it's sent as Bearer … automatically.
Security
Your token stays local. It lives only in the server's environment and is only sent to
CLICKUP_BASE_URL.clickup_requestrefuses full URLs and anything that normalizes outside/api/v2/or/api/v3/.Least privilege. The token has your full ClickUp permissions. Use
CLICKUP_READ_ONLY,CLICKUP_TOOLSETSandCLICKUP_DISABLED_TOOLSto give the model only what it needs.Uploads read local files. Set
CLICKUP_UPLOAD_ROOTSto restrict which foldersfile_pathcan read. Symlinks are resolved before the check.Prompt injection. Task descriptions, comments and docs are untrusted text that the model will read. Keep your client's confirmation prompts on for write and delete tools.
Found a vulnerability? Please report it privately, see SECURITY.md.
Troubleshooting
Symptom | Fix |
| Add the token to the |
| The token is wrong or was regenerated. Copy a fresh one from Settings → Apps. |
| The ID doesn't exist or your token can't see it. Task IDs are the short alphanumeric ones; custom IDs need |
Client is slow or warns about too many tools | Keep the default meta mode (4 tools), or use a smaller |
| Use |
Server doesn't start | Run it in a terminal to see the error: |
Response cut off with | Use paging/filters, or raise |
Server logs (one [clickup-mcp] … ready line on start, plus warnings) go to stderr, which most clients show in their MCP log view.
FAQ
Is there an MCP server that covers the whole ClickUp API? Yes, that's this project. It exposes all 173 operations of ClickUp's public API v2 and v3, generated from the official OpenAPI specs, including Chat, Docs, Attachments, ACLs and Audit Logs.
How do I connect ClickUp to Claude, Cursor or VS Code?
Add the server to your client's MCP config with your ClickUp API token (see Client setup). It runs locally over stdio via npx -y clickup-full-mcp; no hosting needed.
How many tokens does it use? About 700 tokens by default (meta mode, 4 tools) versus ~55,000 when all 173 endpoints are registered as separate tools. See Why 4 tools?.
Can it create tasks, track time, comment, and post in ClickUp Chat? Yes. Anything the ClickUp API can do, including tasks, subtasks, comments, checklists, custom fields, time entries, Docs pages and Chat messages. See Common ClickUp operations.
Can I make it read-only?
Yes: CLICKUP_READ_ONLY=true exposes only GET operations and blocks writes through clickup_request.
Does it work with AI agents and agent SDKs, not just chat apps? Yes. It's a standard stdio MCP server, so any agent framework that can launch MCP servers can use it. Meta mode is especially useful for agents with tight context budgets.
Is it official? No. It's an independent open-source project (MIT) and is not affiliated with ClickUp.
Keeping up with ClickUp
ClickUp's specs are vendored in spec/. A weekly GitHub Action downloads the latest versions, regenerates the tools and the tool reference, and opens a PR when anything changed. To refresh manually:
npm run update-spec && npm run buildFixes for places where the spec doesn't match the live API live in scripts/generate.mjs (NAME_OVERRIDES, JSON_QUERY_PARAMS, UPLOAD_FIELD, queryStyle).
Contributing
Contributions are welcome. See CONTRIBUTING.md for the dev setup, project layout and how the generated code works. Please follow the Code of Conduct.
License
MIT © Kelvin Campelo.
ClickUp's OpenAPI specs in spec/ belong to ClickUp and are included only for reproducible code generation; see NOTICE. "ClickUp" is a trademark of its owner. This project is not affiliated with ClickUp.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Unofficial community ClickUp MCP via personal API token. Not affiliated with ClickUp.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Unofficial ClickUp MCP — wraps the ClickUp REST API v2 (BYO API key)
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseBqualityBmaintenanceLightweight ClickUp MCP server for task management with 37 tools and token-optimized responses to reduce API verbosity.40168 npm4MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage ClickUp workspaces, teams, spaces, folders, lists, tasks, and custom fields via 29 MCP tools with full CRUD operations.5ISC
- AlicenseAqualityCmaintenanceA comprehensive MCP server for the ClickUp API exposing 166 tools to manage Spaces, Folders, Lists, Tasks, Docs, and more, enabling LLMs to read and drive a ClickUp Workspace.10046 PyPI1Apache 2.0
- AlicenseAqualityCmaintenanceEnables interaction with ClickUp workspaces, spaces, folders, lists, tasks, and comments via MCP tools.1Apache 2.0