Skip to main content
Glama

ClickUp MCP Server (clickup-full-mcp)

npm CI License: MIT Node.js 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.

NOTE

Community project, not affiliated with or endorsed by ClickUp.

Contents

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

clickup_search_operations

Finds operations by keyword: "create task", "log time", "send chat message"…

clickup_describe_operation

Returns one operation's full description and JSON input schema, only when it's needed.

clickup_call_operation

Calls any of the 173 operations by name.

clickup_request

Raw escape hatch for any /api/v2 or /api/v3 path.

Measured tools/list size (v1.0.0, tokens ≈ characters ÷ 4):

Mode

Tools

Schema size

Context cost

full (CLICKUP_TOOL_MODE=full)

174

214 KB

~55,000 tokens

full + CLICKUP_TOOLSETS=tasks,comments,time_tracking

42

61 KB

~15,600 tokens

meta (default)

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, JSON custom_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+.

  1. Get a ClickUp API token: ClickUp → your avatar → Settings → Apps → API Token (starts with pk_). OAuth access tokens also work.

  2. Add the server to your MCP client (see Client setup). The quickest way runs it straight from GitHub:

    npx -y clickup-full-mcp

    No install step: npx fetches the npm package on first run. The server is also listed in the official MCP Registry as io.github.KelvinCampelo/clickup-full-mcp.

  3. 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 bug in Inbox to Triage and comment 'moved by triage bot'."

    • "Log 1h30 on task 86abc123 for 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."

TIP

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 ClickUp

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

Common 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

get_tasks

{ "list_id": "901", "statuses": ["to do", "in progress"], "assignees": [183], "include_closed": false }

Search tasks across the workspace

get_filtered_team_tasks

{ "tags": ["bug"], "due_date_lt": 1767225600000, "include_closed": false }

Get one task with its subtasks

get_task

{ "task_id": "86abc123", "include_subtasks": true }

Create a task

create_task

{ "list_id": "901", "body": { "name": "Ship MCP", "markdown_content": "**Why:** …", "priority": 2, "due_date": 1767225600000 } }

Create a subtask

create_task

{ "list_id": "901", "body": { "name": "Write docs", "parent": "86abc123" } }

Change status, assignees, priority

update_task

{ "task_id": "86abc123", "body": { "status": "in review", "priority": 1, "assignees": { "add": [183], "rem": [] } } }

Move a task to another list

move_task

{ "task_id": "86abc123", "list_id": "902", "body": {} }

Delete a task

delete_task

{ "task_id": "86abc123" }

Comments, checklists, tags, custom fields

Goal

Tool

Arguments

Comment on a task

create_task_comment

{ "task_id": "86abc123", "body": { "comment_text": "Deployed to staging", "notify_all": false } }

Read a task's comments

get_task_comments

{ "task_id": "86abc123" }

Add a checklist

create_checklist

{ "task_id": "86abc123", "body": { "name": "QA" } }

Add a checklist item

create_checklist_item

{ "checklist_id": "b955c4dc-…", "body": { "name": "Test on mobile" } }

Tag a task

add_tag_to_task

{ "task_id": "86abc123", "tag_name": "bug" }

List a list's custom fields

get_list_custom_fields

{ "list_id": "901" }

Set a custom field value

set_custom_field_value

{ "task_id": "86abc123", "field_id": "0a52c486-…", "body": { "value": "https://example.com" } }

Time tracking

Goal

Tool

Arguments

Start a timer

start_time_entry

{ "body": { "tid": "86abc123", "description": "code review" } }

Stop the running timer

stop_time_entry

{}

Log time after the fact

create_time_entry

{ "body": { "tid": "86abc123", "start": 1763625600000, "duration": 5400000, "description": "code review" } }

Timesheet for a date range

get_time_entries_within_date_range

{ "start_date": 1763337600000, "end_date": 1763942400000 }

Workspace structure, Docs and Chat

Goal

Tool

Arguments

List workspaces (find your ID)

get_authorized_workspaces

{}

Browse spaces → folders → lists

get_spaces → get_folders → get_lists

{} → { "space_id": "90120001" } → { "folder_id": "90120002" }

Lists that aren't in a folder

get_folderless_lists

{ "space_id": "90120001" }

List Docs / read a Doc's pages

search_docs / get_doc_pages

{} / { "doc_id": "…" }

Write a Doc page in Markdown

create_doc_page

{ "doc_id": "…", "body": { "name": "Release notes", "content": "# v1.2\n…", "content_format": "text/md" } }

Find a Chat channel

get_chat_channels

{}

Post a Chat message

send_chat_message

{ "channel_id": "…", "body": { "type": "message", "content": "Deploy done ✅" } }

Anything not covered by a typed tool

clickup_request

{ "method": "GET", "path": "/api/v2/team/1234567/space", "query": { "archived": false } }

Configuration

All configuration is through environment variables. See .env.example.

Variable

Default

Purpose

CLICKUP_API_TOKEN

(none)

Personal token (pk_…) or OAuth access token. Required for everything except get_access_token.

CLICKUP_WORKSPACE_ID

(none)

Default Workspace (team) ID. Auto-fills team_id / workspace_id and makes them optional in schemas.

CLICKUP_TOOL_MODE

meta

meta = 4 tools for the whole API. full = one tool per endpoint.

CLICKUP_TOOLSETS

all

Comma list of toolsets to expose (works in both modes).

CLICKUP_READ_ONLY

false

Only expose GET operations; clickup_request is limited to GET.

CLICKUP_DISABLED_TOOLS

(none)

Comma list of operation names to hide, e.g. delete_space,delete_folder.

CLICKUP_ENABLE_RAW_REQUEST

true

Expose clickup_request (raw call to any /api/v2 or /api/v3 path).

CLICKUP_UPLOAD_ROOTS

(none)

Comma list of folders that file_path uploads may read from. Unset means any file the user can read.

CLICKUP_MAX_RESPONSE_CHARS

100000

Truncate very large responses.

CLICKUP_TIMEOUT_MS / CLICKUP_MAX_RETRIES

60000 / 3

Request timeout and 429 retries.

CLICKUP_BASE_URL

https://api.clickup.com

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): pass file_path (a local file) or file_base64 + file_name.

  • Errors come back as isError results with the HTTP status and ClickUp's err / ECODE. Unknown or misplaced arguments are rejected before any HTTP call, with a hint (e.g. "request-body fields go inside body").

  • 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_request refuses 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_TOOLSETS and CLICKUP_DISABLED_TOOLS to give the model only what it needs.

  • Uploads read local files. Set CLICKUP_UPLOAD_ROOTS to restrict which folders file_path can 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

CLICKUP_API_TOKEN is not set

Add the token to the env block of your client config, then restart the client.

HTTP 401

The token is wrong or was regenerated. Copy a fresh one from Settings → Apps.

HTTP 404

The ID doesn't exist or your token can't see it. Task IDs are the short alphanumeric ones; custom IDs need custom_task_ids=true + team_id.

Client is slow or warns about too many tools

Keep the default meta mode (4 tools), or use a smaller CLICKUP_TOOLSETS in full mode.

npx not found (Windows, Claude Desktop)

Use "command": "cmd" and "args": ["/c", "npx", "-y", "clickup-full-mcp"], or run from a local clone with node.

Server doesn't start

Run it in a terminal to see the error: CLICKUP_API_TOKEN=pk_xxx npx -y clickup-full-mcp. It logs to stderr.

Response cut off with [truncated: …]

Use paging/filters, or raise CLICKUP_MAX_RESPONSE_CHARS.

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 build

Fixes 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…

    Related MCP Connectors

    Related MCP Servers