Skip to main content
Glama

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-mcp

PowerShell:

$env:CLICKUP_API_KEY = 'pk_REPLACE_WITH_YOUR_PERSONAL_TOKEN'
uvx --from git+https://github.com/alexfdez1010/clickup-mcp.git clickup-mcp

The 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 --help

If 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 = 60

Export 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

clickup_search_operations

Search the bundled catalog by text, tag, and API version. Returns operation summaries and pagination information.

clickup_get_operation

Get the description and full input schema for an operation ID.

clickup_read

Execute a read operation with operation_id, path_params, and query.

clickup_write

Execute a mutating operation with the same arguments plus optional body or files. Omitted in read-only mode.

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

  1. Inspect and call v2_GetAuthorizedTeams to find your Workspace ID. ClickUp's v2 API still calls Workspaces teams in parameter and response names.

  2. 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.

  3. 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}
}
  1. Follow the endpoint's pagination rules to read additional tasks. Catalog search pagination and resource pagination are separate: catalog searches use offset and limit; 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-mcp

The 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 CLICKUP_API_KEY in the environment of the MCP client or its server configuration.

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 uvx is on the client's PATH, or configure its absolute path.

Unknown operation or invalid arguments

Search the catalog, copy the exact ID, and inspect its input schema.

No write tool

Remove --read-only if you intend to allow mutations.

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 tools
clickup_get_operationB
Read-onlyIdempotent

Inspect an operation's description, required path/query parameters, and body schema.

ParametersJSON Schema
NameRequiredDescriptionDefault
operation_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters2/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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_readC
Read-onlyIdempotent

Execute a catalog GET operation. Inspect its schema first. Returns {status, data}.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
path_paramsNo
operation_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters1/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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_operationsA
Read-onlyIdempotent

Search the offline API catalog by words, tag, or version. Returns paginated summaries.

ParametersJSON Schema
NameRequiredDescriptionDefault
tagNo
limitNo
offsetNo
searchNo
versionNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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_writeA
Destructive

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}.
        
ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNo
filesNo
queryNo
path_paramsNo
operation_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters2/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

  1. 4 tool updatesv0.1.0
    • First observedclickup_get_operation
    • First observedclickup_read
    • First observedclickup_search_operations
    • First observedclickup_write

TDQS

A3.5/5.0

Scored across 4 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers