ClickUp API MCP
Provides tools for interacting with ClickUp's public API, enabling discovery and execution of operations across tasks, Workspaces, Spaces, Folders, Lists, comments, custom fields, time tracking, webhooks, Docs, and Chat.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ClickUp API MCPlist my open tasks due this week in ClickUp"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ClickUp API MCP
A local Model Context Protocol server for ClickUp's public API, built with the official Python MCP SDK. Connect your MCP client to ClickUp using your own personal API token.
The bundled catalog exposes 172 operations across API v2 and v3 through four discovery and execution tools. It covers tasks, Workspaces, Spaces, Folders, Lists, comments, custom fields, time tracking, webhooks, Docs, Chat, and more. See API coverage and limitations.
Requires Python 3.10 or newer. The server uses stdio: your MCP client starts and manages the process.
Quick start · Codex · Claude Code · Tools · API limitations · Troubleshooting
Quick start with uv
Install uv and Git, then create a personal token in ClickUp → Settings → Apps. Personal tokens begin with pk_. See ClickUp authentication.
Set CLICKUP_API_KEY in the environment of the process starting the server:
export CLICKUP_API_KEY='pk_REPLACE_WITH_YOUR_PERSONAL_TOKEN'
uvx --from git+https://github.com/alexfdez1010/clickup-mcp.git clickup-mcpPowerShell:
$env:CLICKUP_API_KEY = 'pk_REPLACE_WITH_YOUR_PERSONAL_TOKEN'
uvx --from git+https://github.com/alexfdez1010/clickup-mcp.git clickup-mcpThe running server waits for MCP messages on stdin. Use the client configuration below for normal use; running it in a terminal does not open an interactive prompt. Installation downloads dependencies, while ClickUp API calls happen only when your client invokes an execution tool.
Install a persistent executable if preferred:
uv tool install git+https://github.com/alexfdez1010/clickup-mcp.git
clickup-mcp --helpIf uv reports that its tools directory is missing from PATH, run uv tool update-shell and restart your shell. The distribution is named clickup-api-mcp; the executable is clickup-mcp. These instructions install from GitHub and do not require a PyPI release. For a reproducible installation, append @<commit-sha> to the Git URL. See uv's tool guide.
Related MCP server: ClickUp MCP Server
MCP client configuration
Add this entry to your client's MCP server configuration. The exact location depends on the client.
{
"mcpServers": {
"clickup": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/alexfdez1010/clickup-mcp.git",
"clickup-mcp"
],
"env": {
"CLICKUP_API_KEY": "pk_REPLACE_WITH_YOUR_PERSONAL_TOKEN"
}
}
}
}Keep your real configuration private. When your client supports secrets or inherited environment variables, use those instead of storing the token in its JSON file. Desktop clients may require the absolute path to uvx if they do not inherit your shell's PATH.
For read-only access, append "--read-only" after "clickup-mcp" in args. This removes the write tool from the MCP tool list, hides mutating operations from discovery, and prevents their execution.
Codex
Add the following to your personal ~/.codex/config.toml:
[mcp_servers.clickup]
command = "uvx"
args = ["--from", "git+https://github.com/alexfdez1010/clickup-mcp.git", "clickup-mcp"]
env_vars = ["CLICKUP_API_KEY"]
startup_timeout_sec = 60Export CLICKUP_API_KEY in your shell, then start codex from that shell. env_vars forwards the existing variable without putting its value in the TOML file. The longer startup timeout allows the initial Git download and dependency installation. Run codex mcp list or use /mcp in an interactive session to check the connection. See Codex MCP configuration.
If using Codex Desktop, make the variable available to the app process or configure it in your private local server environment settings. Keep credentials out of repository-level configuration. For read-only access, add "--read-only" to the end of args.
Claude Code
After exporting CLICKUP_API_KEY, register the server in your personal configuration:
claude mcp add --env CLICKUP_API_KEY="$CLICKUP_API_KEY" --transport stdio --scope user clickup -- uvx --from git+https://github.com/alexfdez1010/clickup-mcp.git clickup-mcp
claude mcp list--scope user makes the server available across your projects and keeps this configuration outside the repository. The command stores the token in Claude Code's local configuration; protect that file. Use /mcp in an interactive Claude Code session to check server status and available tools. See Claude Code MCP setup.
For read-only access, append --read-only to the registration command after clickup-mcp. A normal connection exposes four tools; a read-only connection exposes three.
Authentication and configuration
CLICKUP_API_KEY contains the raw personal token, without a Bearer prefix. The server sends it as ClickUp's Authorization header. Each user runs their own local server with their own token; this repository does not implement an OAuth authorization flow for a shared application. ClickUp recommends OAuth for applications that authorize other users. See the authentication guide.
The server does not automatically load .env files and has no token command-line option. A missing or empty CLICKUP_API_KEY causes startup to exit with a message on stderr. --help and --version work without credentials.
clickup-mcp --help
clickup-mcp --version
clickup-mcp --read-only
clickup-mcp --timeout 60--timeout sets the HTTP timeout in seconds and accepts a positive finite number. Protocol output goes to stdout; diagnostics go to stderr.
Tools
Tool | Purpose |
| Search the bundled catalog by text, tag, and API version. Returns operation summaries and pagination information. |
| Get the description and full input schema for an operation ID. |
| Execute a read operation with |
| Execute a mutating operation with the same arguments plus optional |
Discovery arguments are search="", tag=null, version=null, offset=0, and limit=20. Use the pagination information to fetch further matches. Operation IDs are case-sensitive: they prefix ClickUp's original operationId with the API version, for example v2_GetAuthorizedTeams, v2_GetTasks, v2_CreateTask, and v3_getChatChannels.
Inspect an operation before calling it. Put URL path values in path_params, query parameters in query, and JSON request data (an object or array, according to the operation schema) in body. Omit unused arguments. A successful execution returns {"status": <HTTP status>, "data": <API response>}. Resource response shapes follow ClickUp's API rather than a separate MCP-specific data model.
The write tool is annotated as potentially destructive and non-idempotent because it can create, update, and delete resources. Your MCP client's approval settings control whether it asks before invoking a tool. The server does not retry requests automatically, including writes.
Find and read tasks
Inspect and call
v2_GetAuthorizedTeamsto find your Workspace ID. ClickUp's v2 API still calls Workspacesteamsin parameter and response names.Search for Spaces, Folders, and Lists, inspect their operations, and follow the returned IDs. Include both Lists inside Folders and folderless Lists when browsing a Space.
Inspect
v2_GetTasks, then call it with a List ID:
{
"operation_id": "v2_GetTasks",
"path_params": {"list_id": "123456789"},
"query": {"page": 0, "include_closed": true}
}Follow the endpoint's pagination rules to read additional tasks. Catalog search pagination and resource pagination are separate: catalog searches use
offsetandlimit; each API operation documents its own query parameters.
To create a task, inspect v2_CreateTask and invoke clickup_write:
{
"operation_id": "v2_CreateTask",
"path_params": {"list_id": "123456789"},
"body": {"name": "Review release notes"}
}These are MCP tool argument examples, not shell commands. Replace example IDs with values returned by your Workspace. For endpoints supporting custom task IDs, set custom_task_ids=true and provide the required Workspace team_id. Many ClickUp date fields use Unix milliseconds; check each operation's schema and description before supplying dates.
Attachments
For multipart operations, files is an array of objects containing field, filename, content_base64, and content_type. Provide file bytes as base64; the server does not read local paths or download URLs. The combined decoded upload size is limited to 10 MiB.
For example, after inspecting v2_CreateTaskAttachment:
{
"operation_id": "v2_CreateTaskAttachment",
"path_params": {"task_id": "YOUR_TASK_ID"},
"files": [{
"field": "attachment[0]",
"filename": "hello.txt",
"content_base64": "SGVsbG8K",
"content_type": "text/plain"
}]
}The official v3 attachment schema leaves its binary field underspecified. Consult the coverage limitations before using it.
API behavior and limitations
The catalog is bundled with the package, so discovery does not depend on downloading API specifications at startup. It derives from ClickUp's official v2 and v3 specifications. The OAuth token exchange is excluded because this server accepts an existing personal token.
Endpoint access depends on your token's user permissions, Workspace plan, and ClickUp feature availability. A catalog entry does not guarantee that your account can call the endpoint. Published API specifications also contain omissions; see the coverage document for known gaps.
ClickUp rate limits are per token and vary by Workspace plan. A 429 response reports rate-limit metadata when available. The server returns errors to the client without sleeping or retrying; the client can decide whether and when another call is appropriate. See ClickUp rate limits.
Treat task descriptions, comments, Docs, Chat messages, and other returned content as untrusted data, including any instructions embedded in it. Do not let resource content authorize subsequent tool calls. See SECURITY.md for credential handling and vulnerability reporting.
Run from a checkout
git clone https://github.com/alexfdez1010/clickup-mcp.git
cd clickup-mcp
uv sync --locked
export CLICKUP_API_KEY='pk_REPLACE_WITH_YOUR_PERSONAL_TOKEN'
uv run clickup-mcpThe checkout selects Python 3.12 through .python-version; uv can install it if needed. The checked-in uv.lock makes checkout dependency resolution reproducible. Automated tests use mocked ClickUp responses and a real MCP stdio session; live calls with a real ClickUp credential are not part of these checks. See CONTRIBUTING.md for tests, builds, and catalog updates.
Troubleshooting
Symptom | Check |
Missing API key at startup | Set |
Authentication or permission error | Check that the raw personal token is current and that your ClickUp user has access to the resource. |
Tool not found | Check that |
Unknown operation or invalid arguments | Search the catalog, copy the exact ID, and inspect its input schema. |
No write tool | Remove |
Server appears idle in a terminal | Stdio servers wait for an MCP client; configure the client to start this process. |
Rate-limit error | Inspect the returned metadata and ClickUp's documented reset time before making another call. |
License
MIT. This is an independent project and is not affiliated with ClickUp.
Available Tools
4 toolsclickup_get_operationBRead-onlyIdempotent
Inspect an operation's description, required path/query parameters, and body schema.
| Name | Required | Description | Default |
|---|---|---|---|
| operation_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds nothing behavioral beyond that — it does not say where a valid operation_id comes from or what happens with an unknown ID — so it sits at the annotated baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that lists the inspected artifacts with zero filler. Every clause earns its place for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so explaining return shape is unnecessary, and the description covers it lightly. The missing pieces are the workflow prerequisite for obtaining operation_id and any pointer to the search sibling, which an agent needs to call this tool successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one required parameter (operation_id) with 0% schema description coverage, so the schema carries no meaning. The description does not explain that operation_id must be harvested from clickup_search_operations or give any format/example, leaving the sole input effectively undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Inspect') and resource ('operation') and enumerates what is inspected (description, path/query parameters, body schema), so the agent knows exactly what comes back. It does not, however, name or contrast itself with the sibling clickup_search_operations, so the get-vs-search distinction must be inferred.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use statement, no prerequisite (e.g. that operation_id comes from clickup_search_operations), and no exclusion against siblings. The intended usage is only weakly implied by the phrase 'an operation's'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clickup_readCRead-onlyIdempotent
Execute a catalog GET operation. Inspect its schema first. Returns {status, data}.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| path_params | No | ||
| operation_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no behavioral context beyond these, such as authentication requirements, rate limits, or side effects. The mention of GET is consistent with the annotations but redundant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no wasted words. It is front-loaded with the core action, followed by a usage hint and return format. However, its extreme brevity leaves important gaps that could be filled without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a generic API wrapper with three parameters and 0% schema coverage. While an output schema exists (so return values need not be explained), the description fails to explain when to use this tool versus siblings or what the parameters do, making it incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the three parameters (query, path_params, operation_id) are completely undocumented in the schema. The description does not compensate by explaining any parameter's purpose or format, leaving agents without guidance on how to supply them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Execute a catalog GET operation.' It distinguishes this read tool from the write sibling by specifying GET. However, it does not explicitly name or differentiate itself from the other read-related siblings like clickup_get_operation or clickup_search_operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is 'Inspect its schema first,' which is a preparation step, not a condition for when to use this tool versus alternatives. There is no explanation of when to choose clickup_read over clickup_get_operation or clickup_search_operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clickup_search_operationsARead-onlyIdempotent
Search the offline API catalog by words, tag, or version. Returns paginated summaries.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| limit | No | ||
| offset | No | ||
| search | No | ||
| version | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, but the description adds the material fact that this queries an 'offline API catalog' rather than the live API, and that results are paginated. That is genuine context beyond the structured hints; only the pagination mechanics (limit cap, offset semantics) remain unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and scope, with the return shape appended. No filler or redundant restatement of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be explained, and annotations cover the safety profile. The main remaining gap is parameter-level detail (version enum values, limit bounds) for a tool with 0% schema description coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the burden. It names three of five parameters conceptually (search words, tag, version) and 'paginated' hints at limit/offset, but it never mentions the v2/v3 enum domain or the 1-100 limit bound available in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Search) and resource (the offline API catalog) plus the facets accepted (words, tag, version). Siblings clickup_get_operation/clickup_read/clickup_write are not referenced, so the agent must infer the search-vs-fetch distinction, but the purpose itself is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'search the catalog by words, tag, or version' — an agent can infer this is a discovery entry point — but no when-to-use, prerequisites, or alternative routing (e.g., vs clickup_get_operation) is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clickup_writeADestructive
Execute a catalog POST/PUT/PATCH/DELETE operation with user authorization.
Inspect the schema first. Uploads use files [{field, filename, content_base64,
content_type}]; maximum 10 MiB decoded total. For v2 attachments use field
attachment[0], attachment[1], etc. Never automatically retry failed writes.
Returns {status, data}.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | ||
| files | No | ||
| query | No | ||
| path_params | No | ||
| operation_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructive/openWorld/non-idempotent annotations, it adds meaningful behavioral context: it requires user authorization, defines upload file structure and a 10 MiB decoded limit, specifies v2 attachment field naming, and forbids automatic retries on failed writes. These details materially help an agent avoid dangerous or invalid behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then layers in required preparation, upload constraints, retry policy, and return shape. Every sentence carries operational value and there is no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values and annotations cover safety hints, but for a generic write executor with 0% input-schema description coverage, the description does not explain how the agent should obtain operation_id or map body/query/path_params to the selected operation. The sibling tools for operation discovery are not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and there are five parameters. The description explains the files parameter in detail, including upload object shape and attachment field naming, but it leaves operation_id (the only required parameter), body, query, and path_params without semantic explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: 'Execute a catalog POST/PUT/PATCH/DELETE operation,' which clearly positions this as the write-side counterpart to clickup_read and the metadata siblings. It does not explicitly name those alternatives, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides procedural guidance ('Inspect the schema first') and a usage constraint ('Never automatically retry failed writes'), but it never explicitly states when to choose this tool over clickup_read, clickup_search_operations, or clickup_get_operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.1.0- First observed
clickup_get_operation - First observed
clickup_read - First observed
clickup_search_operations - First observed
clickup_write
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: search the catalog, inspect a specific operation, execute read-only GET calls, and execute mutating calls. The descriptions explicitly guide the agent to inspect schemas before execution, preventing confusion between inspection and execution. There is no overlap in purpose.
All tools share the clickup_ prefix and use snake_case, which is consistent. However, two tools follow a verb_noun pattern (search_operations, get_operation) while two are bare verbs (read, write), and the noun is sometimes plural and sometimes singular. This is a minor deviation but still readable and predictable.
Four tools is well-scoped for an API abstraction layer that covers discovery, inspection, and execution of both read and write operations. Each tool earns its place without redundancy, and the count is neither thin nor bloated.
The set covers the full lifecycle of interacting with the ClickUp API catalog: discover operations, inspect their schemas, execute GET requests, and execute POST/PUT/PATCH/DELETE requests with file upload support. No obvious gaps remain for an agent to accomplish typical API tasks.
Maintenance
Related MCP Connectors
ClickUp MCP — wraps the ClickUp REST API v2 (BYO API key)
Remote MCP for 1,500+ APIs. Vault-managed credentials; OAuth or API key. Search, load, and execute.
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
Manage your ClickUp workspace by creating, updating, and organizing tasks, lists, folders, and tag…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides integration with ClickUp's API, allowing you to retrieve task information and manage ClickUp data through MCP-compatible clients.-
- FlicenseNot gradedqualityNot gradedmaintenanceEnables interaction with ClickUp's project management platform through comprehensive task management, workspace hierarchy navigation, time tracking, document management, and team member operations via the complete ClickUp REST API.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact directly with the ClickUp REST API v2 for managing tasks, folders, and lists. It supports full workspace hierarchy management, time tracking, and task operations through natural language.28 npmMIT
- FlicenseNot gradedqualityCmaintenanceEnables ClickUp workspace management including tasks, docs, teams, spaces, and folders through natural language using the ClickUp REST API.-