Skip to main content
Glama
ClickUp MCP Server
by asaphe

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

Related MCP server: ClickUp MCP Server

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

Variable

Description

CLICKUP_API_TOKEN

Personal API token from https://app.clickup.com/settings/apps

WORKSPACE_ID

Your ClickUp workspace (team) ID

Optional — Sprint Detection

Variable

Description

DEVELOPMENT_SPACE_ID

Space ID containing your sprints. Required for sprint tools.

SPRINTS_FOLDER_ID

Folder ID within the space that holds sprint lists. Required for sprint tools.

Optional — Team Labels

Variable

Description

COMPONENT_TEAM_FIELD_ID

Custom field ID for Component/Team labels

CLICKUP_TEAM_LABELS

JSON mapping of team names to label IDs (see below)

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

Variable

Description

CLICKUP_TASK_TYPES

JSON mapping of task type names to custom task type IDs (see below). Enables the task_type parameter on create_task, create_sprint_task, update_task and bulk_update_tasks, and the task_type field in task details.

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

Variable

Default

Description

API_BASE_URL

https://api.clickup.com/api/v2

ClickUp API base URL

REQUEST_TIMEOUT

15.0

HTTP request timeout in seconds

MAX_RETRIES

3

Max retry attempts for failed/rate-limited requests

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

Tool

Description

get_current_sprint

Auto-detect the active sprint by date

refresh_sprint_cache

Force-refresh the cached sprint

get_sprint_tasks

List tasks in the current sprint (filter by assignee/status)

Task Management

Tool

Description

get_task

Get task details by ID (DEV-1234 or UUID)

create_task

Create a task in any list

create_sprint_task

Create a task in the current sprint (auto-assign, team, points)

update_task

Update status, assignee, description, points, dates

search_tasks

Search tasks by name

get_my_tasks

Get tasks assigned to the current user

get_list_tasks

Get all tasks in a specific list

move_task_to_list

Move a task to a different list

bulk_update_tasks

Batch-update status/team/assignee across multiple tasks

ensure_task_fields

Check and fix missing fields (assignee, team, points)

delete_task

Delete a task permanently

Comments

Tool

Description

add_task_comment

Post a comment on a task. Single-line **bold** and @[Full Name] / @[email] render as rich text; backtick code, and bold that contains it, stay literal. Each mention must be listed in the mentions argument, sit outside bold and match exactly one current workspace member, and each mentions entry must appear as an @[...], or nothing is posted

get_task_comments

Retrieve comments from a task

Reporting

Tool

Description

get_sprint_report

Sprint report by assignee with status counts and at-risk flags

Workspace

Tool

Description

get_current_user

Show the authenticated user

get_workspace_hierarchy

Browse spaces, folders, and lists

task_url

Get the ClickUp URL for a task

add_tag_to_task

Add a tag to a task

list_teams

List available team labels

check_team_labels

Check configured team labels against live ClickUp options

Docs

Tool

Description

create_doc

Create a native ClickUp Doc (v3 API) with one page of markdown content; returns its URL. Create-only, PRIVATE by default — sharing is a manual follow-up in the ClickUp UI.

update_doc_page

Overwrite an existing Doc page's content in place (replace-only), with an optional retitle; returns its URL.

get_doc

Get a Doc's metadata (name, parent location, visibility).

get_doc_pages

Get every page of a Doc, content included, as a flat list — sub-pages are flattened in, not dropped.

get_doc_page

Get a single page's content by doc_id/page_id.

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

Available Tools

28 tools
add_tag_to_taskB

Add a tag to a task.

Args: task_id: Task ID (custom like DEV-1234 or UUID). tag_name: Tag name to add.

Inputs: task_id (required), tag_name (required). Returns: result

add_task_commentA

Add a comment to a task.

Args: task_id: Task ID (custom like DEV-1234 or UUID). comment_text: Comment text (plain text).

Inputs: task_id (required), comment_text (required). Returns: result

bulk_update_tasksA
Destructive

Update multiple tasks at once. Verify the task_ids list before calling.

This is a convenience tool that applies the same update to multiple tasks. Partial failures are reported — some tasks may succeed while others fail.

Args: task_ids: List of task IDs (custom or UUID). Double-check before calling. status: Set status on all tasks. assignee_add: Add assignee (user ID) to all tasks. team: Set Component/Team label on all tasks. points: Set story points on all tasks.

Inputs: task_ids (required), team, points, status, +1 more. Returns: result

check_team_labelsA
Read-only

Audit configured team label IDs against live ClickUp field options.

Args: space_id: Space to check. Defaults to the configured development space.

Inputs: space_id. Returns: result

create_docA

Create a native ClickUp Doc with one page of content, and return its URL.

Use this for shareable reports/RFCs that need real markdown tables and headers — a task description degrades tables and isn't a durable review surface. The doc is created PRIVATE by default; sharing it with specific people or the workspace is a separate step you take in the ClickUp UI, not something this tool does.

Two sequential API calls (create doc, then create its page) with no rollback: ClickUp's v3 Docs API exposes no delete endpoint for docs or pages, so if the page call fails after the doc call succeeds, an empty Doc is left behind — check the workspace for it if this raises. For the same reason, correcting a mistake (wrong content, a bad title) should use update_doc_page on the existing doc_id/page_id rather than calling create_doc again — a second create_doc call orphans the first Doc with no way to remove it.

Args: name: Doc title. content: Page body. Markdown by default (see content_format). parent_id: Space/Folder/List/Workspace ID to create the doc under. Defaults to the configured development space — which is a Space, so if parent_type is "workspace"/"everything" you must pass a matching parent_id explicitly or the doc lands in the wrong place. parent_type: One of "space", "folder", "list", "everything", "workspace" — must match what parent_id actually refers to. content_format: "text/md" (default) or "text/plain". visibility: "PRIVATE" (default), "PUBLIC", "PERSONAL", or "HIDDEN".

Inputs: name (required), content (required), parent_id, visibility, +2 more. Returns: result

create_sprint_taskA

Create a task in the current sprint with sensible defaults.

Auto-resolves the current sprint list and (optionally) the current user. If parent_task_id lives in a different list than the current sprint, the task is created there instead (ClickUp requires parent and child to share a list) and will not appear in sprint queries — check list_id_override in the result.

Requires DEVELOPMENT_SPACE_ID and SPRINTS_FOLDER_ID to be configured.

Args: name: Task title. team: Component/Team label. See list_teams for available values. description: Task description. points: Story points. Omitted unless given. assign_to_me: Assign to the authenticated user (default: true). parent_task_id: Parent task ID (custom like DEV-1234 or UUID) for creating subtasks. status: Initial status. Omitted unless given, so the sprint list's own default status applies. Pass an explicit value to override it.

Inputs: name (required), team, points, status, +3 more. Returns: result

create_taskA

Create a new task in a specific list.

For sprint tasks, prefer create_sprint_task which auto-resolves the sprint list.

Args: name: Task title. list_id: Target list ID. Use get_current_sprint or get_workspace_hierarchy to find IDs. Always required, but if parent_task_id names a task in a different list, the task is created there instead (ClickUp requires parent and child to share a list) — see list_id_override in the result. description: Task description (markdown supported). assignee_id: User ID to assign. Use get_current_user to find your ID. status: Initial status. Omitted unless given, so the target list's own default status applies. ClickUp configures status sets per list, so no value is safe to impose on an arbitrary list_id. points: Story points. team: Component/Team label. See list_teams for available values. parent_task_id: Parent task ID for creating subtasks. Its list wins over list_id when the two differ. priority: 1=urgent, 2=high, 3=normal, 4=low.

Inputs: name (required), list_id (required), team, points, +5 more. Returns: result

delete_taskA
Destructive

Delete a task permanently. This action cannot be undone.

Args: task_id: Task ID, either a custom ID or ClickUp UUID.

Inputs: task_id (required). Returns: result

ensure_task_fieldsA

Check (and optionally fix) that tasks have required fields set.

By default checks assignee, team, and points. Useful for sprint compliance.

Args: task_ids: List of task IDs to check. required_fields: Fields to check. Default: ["assignee", "team", "points"]. fix: If true, apply defaults to fill missing fields. If false, report only. default_assignee_id: User ID to assign if assignee is missing and fix=true. default_team: Team label to set if team is missing and fix=true. default_points: Points to set if missing and fix=true.

Inputs: task_ids (required), fix, default_team, default_points, +2 more. Returns: result

get_current_sprintA
Read-onlyIdempotent

Get the current sprint's info (list ID, name, date range).

Auto-detected by date. Cached per session — use refresh_sprint_cache if the sprint rolled over.

Requires DEVELOPMENT_SPACE_ID and SPRINTS_FOLDER_ID to be configured.

Inputs: no named parameters. Returns: result

get_current_userA
Read-onlyIdempotent

Get the current authenticated user's info (ID, username, email).

Cached per session. Use the ID for assignee operations.

Inputs: no named parameters. Returns: result

get_docA
Read-only

Get a Doc's metadata — name, parent location, visibility.

Use get_doc_page or get_doc_pages to read page content. ClickUp's public API has no Doc-comment endpoint, so this cannot retrieve comment threads on a Doc.

Args: doc_id: The Doc's ID, as returned by create_doc.

Inputs: doc_id (required). Returns: result

get_doc_pageA
Read-only

Get a single Doc page's content.

Mirrors update_doc_page's doc_id/page_id pair — most useful when you already have both IDs from a prior create_doc/update_doc_page call.

Args: doc_id: The Doc's ID, as returned by create_doc. page_id: The page's ID, as returned by create_doc. content_format: "text/md" (default) or "text/plain".

Inputs: doc_id (required), page_id (required), content_format. Returns: result

get_doc_pagesA
Read-only

Get every page of a Doc, content included, as a flat list.

Use this to read a whole multi-page Doc in one call. Sub-pages (nested under a parent page in the ClickUp v3 response) are flattened into the same list alongside their parent, not dropped. For a single known page, get_doc_page avoids fetching pages you don't need.

Args: doc_id: The Doc's ID, as returned by create_doc. content_format: "text/md" (default) or "text/plain". max_page_depth: How many levels of nested sub-pages to include. -1 (default) returns every page.

Inputs: doc_id (required), content_format, max_page_depth. Returns: result

get_list_tasksA
Read-only

Get all tasks in a specific list (backlog, epic, tech debt, etc.).

Args: list_id: List ID. Use get_workspace_hierarchy to discover list IDs. status: Filter by status (e.g., "todo", "in progress"). include_closed: Include closed/done tasks (default: false). subtasks: Include subtasks in results (default: true). Inverts search_tasks' own default; pass false to match it.

Inputs: list_id (required), status, subtasks, include_closed. Returns: result

get_my_tasksA
Read-only

Get tasks assigned to the current user across all lists.

Convenience wrapper around search_tasks with automatic user resolution.

Args: query: Text search query (client-side filtered — see search_tasks). status: Filter by status(es). list_id: Limit to a specific list. date_created_after: ISO date or Unix millis — only tasks created after this. date_updated_after: ISO date or Unix millis — only tasks updated after this. include_closed: Include closed/done tasks (default: false). page: Page number (0-indexed). subtasks: Include subtasks in results (default: true). Inverts search_tasks' own default, since a personal task list is mostly subtasks; pass false to match search_tasks.

Inputs: page, query, status, list_id, +4 more. Returns: result

get_sprint_reportA
Read-only

Generate a structured sprint status report.

Returns tasks grouped by assignee with status summary, at-risk flags, unassigned task warnings, and optionally linked GitHub PRs.

Requires DEVELOPMENT_SPACE_ID and SPRINTS_FOLDER_ID to be configured.

Args: team: Filter to a Component/Team label (e.g., "backend", "devops"). If omitted, includes all tasks in the sprint. Requires CLICKUP_TEAM_LABELS to be configured for filtering. include_pr_links: Extract GitHub PR links from task descriptions and comments (default: true). Adds latency for comment fetching.

Inputs: team, include_pr_links. Returns: result

get_sprint_tasksA
Read-only

List tasks in the current sprint, optionally filtered.

Includes tasks directly in the sprint list and tasks tagged for the sprint.

Args: assignee: Filter by assignee. Use "me" for the current user, or a username. status: Filter by status (e.g., "in progress", "done", "todo").

Inputs: status, assignee. Returns: result

get_taskA
Read-only

Get detailed info for a task.

Accepts custom IDs (DEV-1234) or UUIDs. Returns status, assignees, description, subtasks, priority, team label, and more.

Args: task_id: Task ID (custom like DEV-1234 or UUID). include_subtasks: Include subtask details (default: true).

Inputs: task_id (required), include_subtasks. Returns: result

get_task_commentsA
Read-only

Get all comments on a task.

Args: task_id: Task ID (custom like DEV-1234 or UUID).

Inputs: task_id (required). Returns: result

get_workspace_hierarchyA
Read-only

Browse the workspace folder/list hierarchy.

Returns folders and lists in the given space. Use this to discover list IDs for creating tasks or browsing backlogs.

Args: space_id: Space to browse. Defaults to the configured DEVELOPMENT_SPACE_ID. max_depth: How deep to recurse (1=folders only, 2=folders+lists, 3=+sublists).

Inputs: space_id, max_depth. Returns: result

list_teamsA
Read-only

List available Component/Team labels and their IDs.

Use team names (lowercase) when creating or updating tasks with a team parameter. Returns the configured CLICKUP_TEAM_LABELS mapping, or an empty object if not configured.

Inputs: no named parameters. Returns: result

move_task_to_listA

Move a task to a different list.

Args: task_id: Task ID (custom like DEV-1234 or UUID). list_id: Target list ID.

Inputs: list_id (required), task_id (required). Returns: result

refresh_sprint_cacheA
Idempotent

Clear and re-fetch the cached sprint info.

Use when a sprint rolls over mid-session or if get_current_sprint returns stale data.

Inputs: no named parameters. Returns: result

search_tasksA
Read-only

Search tasks across the workspace.

Supports filtering by query text, status, assignee, list, and dates. Returns paginated results with has_more indicator.

Note: query is applied as a client-side filter after fetching each page from the API. The has_more flag reflects the API's pagination state, not whether additional matching results exist. Callers should continue paginating while has_more is true if they need exhaustive results.

Args: query: Text search query (client-side filtered — see note above). status: Filter by status(es). assignee_id: Filter by assignee user ID. Use get_current_user for your ID. list_id: Limit to a specific list. include_closed: Include closed/done tasks (default: false). date_created_after: ISO date or Unix millis — only tasks created after this. date_updated_after: ISO date or Unix millis — only tasks updated after this. page: Page number (0-indexed). Check has_more in response for pagination. subtasks: Include subtasks in results (default: false).

Inputs: page, query, status, list_id, +5 more. Returns: result

task_urlA
Read-onlyIdempotent

Get the ClickUp URL for a task. Accepts custom IDs (DEV-1234) or UUIDs.

Args: task_id: Task ID (custom like DEV-1234 or UUID).

Inputs: task_id (required). Returns: result

update_doc_pageA
Destructive

Overwrite an existing Doc page's content in place, and return its URL.

Use this to correct a previously published Doc (wrong content, a bad title) instead of calling create_doc again — the v3 Docs API has no delete endpoint, so a second create_doc call orphans the first Doc with no way to remove it. This edits the original doc_id/page_id directly, so the existing URL keeps working.

Always replaces the full page content — the underlying API also supports append/prepend edit modes, but this tool doesn't expose them: the shared HTTP client retries transport failures, and a retry after a lost response (server applied the edit, client never saw it) would silently double-apply an append/prepend. A retried replace converges to the same content either way, so it's safe.

Args: doc_id: The Doc's ID, as returned by create_doc. page_id: The page's ID, as returned by create_doc. content: New page content, replacing the page in full. name: New page title. Leave unset to keep the existing title. content_format: "text/md" (default) or "text/plain".

Inputs: doc_id (required), content (required), page_id (required), name, +1 more. Returns: result

update_taskA

Update fields on a task. Only specified fields are changed.

Args: task_id: Task ID (custom like DEV-1234 or UUID). name: New task name. status: New status (e.g., "done", "in progress", "in review"). priority: 1=urgent, 2=high, 3=normal, 4=low. points: Story points. description: Replace entire description. Use append_description to add text instead. append_description: Append text to existing description (separated by newline). assignee_add: User ID to add as assignee. assignee_remove: User ID to remove from assignees. parent_task_id: Parent task ID to nest this task under (custom like DEV-1234 or UUID), including re-parenting a task that has never had a parent. Setting this also moves the task to the parent's list.

Inputs: task_id (required), name, points, status, +6 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 28 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, with detailed descriptions that clarify scopes (e.g., get_task vs get_sprint_tasks vs get_list_tasks vs search_tasks). Even the sprint-specific create/get tools are clearly delineated from their general counterparts, and docs tools distinguish metadata, single-page, and all-pages retrieval. No two tools appear to do the same thing.

    Naming Consistency4/5

    The overwhelming majority follow a consistent snake_case verb_noun pattern (get_task, create_task, update_doc_page, list_teams). The only notable deviation is task_url, which is a noun phrase rather than a verb-led name, though its purpose is still clear. Overall, the naming is predictable and readable.

    Tool Count2/5

    At 28 tools, the set exceeds the 25-tool threshold where it becomes too heavy, even though it covers multiple domains (tasks, sprints, docs, teams). The count feels bloated; several tools are convenience wrappers (e.g., get_my_tasks, create_sprint_task) that could potentially be merged or documented as optional add-ons without sacrificing functionality.

    Completeness4/5

    The tool surface provides strong CRUD and workflow coverage for tasks (create, get, update, delete, search, list, move, bulk update, comments, tags) and sprints (current sprint, tasks, report). Docs have create and update, but no delete or share tool (noted as API/UI limitations). Minor gaps include no remove-tag tool and no direct way to update doc metadata beyond page content, but these are workable.

    Related MCP Connectors

    Related MCP Servers