ClickUp任务管理MCP服务

ClickUp MCP Server

A Model Context Protocol (MCP) server that connects Claude Code and Claude Desktop to ClickUp. Provides task management, sprint tracking, reporting, workspace navigation, and Doc creation through 28 tools.

Features

• Task management — create, update, search, and bulk-edit tasks
• Sprint tracking — auto-detect current sprint, list sprint tasks, filter by assignee/status
• Reporting — sprint reports with at-risk detection, PR link extraction, status summaries
• Workspace navigation — browse spaces, folders, lists; resolve custom task IDs
• Comments — read and write task comments
• Docs — create a native ClickUp Doc with real markdown tables/headers, unlike a task description

Prerequisites

• Python 3.12+
• uv (brew install uv)
• A ClickUp personal API token

Quick Start

uv tool install "clickup-mcp-server @ git+https://github.com/asaphe/clickup-mcp.git"
clickup-mcp-server setup --code

The setup script walks you through:

1. Token retrieval (1Password integration or manual paste)
2. Workspace configuration (workspace ID required, sprint/team IDs optional)
3. Client registration (Claude Code, Claude Desktop, or both)
4. Automatic restart of Claude Desktop if running

To configure Claude Desktop instead, run:

clickup-mcp-server setup --desktop

To configure both clients:

clickup-mcp-server setup --both

Alternative: Run from a Local Clone

Use this flow when you want to hack on the server itself:

git clone https://github.com/asaphe/clickup-mcp.git
cd clickup-mcp
uv sync --dev
uv tool install --editable .
python3 setup_mcp.py

This uses the same setup wizard, but runs it from the repo root layout used by this public package. Run uv tool install --editable . first: the setup wizard only installs clickup-mcp-server via uv tool install when it isn't already on your PATH, so an editable install done beforehand is preserved instead of being replaced by the published GitHub version.

Configuration

All configuration is via environment variables. Only CLICKUP_API_TOKEN and WORKSPACE_ID are required — the rest enable optional features.

Required

Optional — Sprint Detection

Optional — Team Labels

Example CLICKUP_TEAM_LABELS:

{"backend": "uuid-1", "frontend": "uuid-2", "example-team": "uuid-3"}

Team names are matched ignoring case (Unicode case folding, so Straße matches STRASSE), and two names that are equal ignoring case, or one name given twice, make the value invalid. Label IDs must be integers or strings that are not empty or whitespace-only; an invalid value is ignored as a whole (one bad ID disables every team label), and the setup wizard rejects it.

Optional — Task Types

Example CLICKUP_TASK_TYPES:

{"task": 0, "bug": 1234, "epic": 5678}

Names are matched ignoring case, as team names are, and two names that are equal ignoring case, or one name given twice, make the value invalid. Without this variable, tasks are created with ClickUp's default type and task_type is rejected. IDs must be integers (a quoted integer such as "1234" is also accepted); an invalid value is ignored as a whole (one bad ID disables the whole mapping), and the setup wizard rejects it.

Optional — Tuning

Finding Your IDs

• Workspace ID: Settings → Workspaces → look at the URL or API response
• Space ID: Click on a Space → the ID is in the URL (/s/{space_id}/...)
• Folder ID: Click on a Folder → inspect the URL or use the get_workspace_hierarchy tool
• Custom Field ID: Use the ClickUp API: GET /list/{list_id}/field
• Team Label IDs: Use the ClickUp API: GET /list/{list_id}/field → find the labels dropdown field → extract option IDs
• Task Type IDs: Use the ClickUp API: GET /team/{workspace_id}/custom_item → each custom task type's id

Tools

28 tools across 6 categories:

Sprint Management

Task Management

Comments

Reporting

Workspace

Docs

ClickUp's v3 Docs API has no DELETE endpoint for Docs or Pages — confirmed against developer.clickup.com's own llms.txt index and public OpenAPI spec, and empirically (a live DELETE call against a real doc returned 405 Method Not Allowed, not 404, meaning the route exists but the verb is rejected). So there's no delete_doc tool, and update_doc_page is replace-only by design: the client retries transport errors, including a timeout that can fire after the server already applied the edit — a replace is idempotent under retry, but append/prepend would silently double-apply.

ClickUp's public API also has no Doc/page comment endpoint (only task/list/view comments exist) — reading a Doc's comment panel still requires the browser.

Usage Examples

In Claude Code or Claude Desktop, just ask naturally:

• "show my tasks"
• "sprint report for backend"
• "create a task for fixing the login bug"
• "mark DEV-1234 as done"
• "what's the current sprint?"
• "show unassigned tasks in the sprint"
• "write this up as a doc so the tables render properly"
• "read that doc back to me"

Key Patterns

• Task IDs: Both custom IDs (DEV-1234, PROJ-456) and UUIDs are accepted everywhere
• "me" as assignee: Resolved automatically from the API token
• Sprint auto-detection: Current sprint is detected by date and cached per session
• Rate limiting: Automatic retry with exponential backoff on 429 responses
• Concurrent comment fetching: Sprint reports fetch PR links from comments with bounded concurrency

Coexistence with Built-in ClickUp MCP

This server works alongside the official ClickUp MCP connector. The built-in handles features not covered here (time tracking, chat, and a Doc's comment panel — ClickUp's public API has no Doc-comment endpoint). Doc create/read/update are covered here; deletion isn't possible via either server, since the v3 Docs API exposes no delete endpoint. You can register both, though having both may cause tool-selection ambiguity for overlapping operations.

Development

uv sync --dev
uv run pytest
uv run mypy clickup_mcp_server
uv run ruff check .

Architecture

clickup_mcp_server/
  server.py       — MCPServer entry point and instructions
  client.py       — Async HTTP client with retry and rate-limit handling
  config.py       — Settings (env var based, no hardcoded IDs)
  models.py       — Pydantic models for API responses
  comment_markup.py — **bold** / @[mention] markup → rich comment blocks
  tools/
    sprint.py     — Sprint detection and caching
    tasks.py      — Task CRUD, search, bulk operations
    comments.py   — Comment read/write
    reporting.py  — Sprint reports with at-risk detection
    workspace.py  — User info, workspace members, hierarchy, tags
    docs.py       — Doc create/read/update (v3 API)

License

MIT