amazing-clickup-mcp 0.1.1

MCP server for the ClickUp public API (v2 + v3, stdio).

ClickUp MCP Server (amazing-clickup-mcp)

A comprehensive Model Context Protocol server for the ClickUp public API (v2 + v3), built on the official MCP Python SDK (FastMCP, stdio transport). It exposes 166 tools covering nearly the entire ClickUp surface — Spaces, Folders, Lists, Views, Docs, Tasks, Comments, Checklists, Tags, Custom Fields, Time Tracking, Goals, Members, Guests, Webhooks, Chat, and more — so an LLM can read and drive a ClickUp Workspace on your behalf.

The PyPI distribution and console script are both amazing-clickup-mcp (the bare clickup-mcp name is taken on PyPI by an unrelated package). Always run uvx amazing-clickup-mcp — never uvx clickup-mcp.

Features

• Full API coverage (166 tools). v2 and v3 endpoints across 22 resource groups — Spaces, Folders, Lists, Views, Docs, Tasks, Comments, Checklists, Tags, Custom Fields, Time Tracking 2.0, Relationships, Attachments, Goals, Members & User Groups, Guests, Users, Webhooks, Workspace admin, Chat channels, Chat messages, and a health check.
• Statuses managed via payloads. ClickUp has no dedicated statuses endpoint; create and update Space/Folder/List objects with statuses/override_statuses payloads.
• Docs created in-place (v3). Create a Doc directly in its final Space/Folder/List/ Everything location — no drag-later.
• Dual-format responses. Markdown for humans and LLMs (default) or JSON for programmatic use, selectable per call via response_format.
• Strict input validation. One pydantic v2 model per tool (extra="forbid", field-level constraints) so malformed calls fail fast with a clear message.
• Uniform error mapping. 400/401/403/404/429, timeouts, and connection errors are normalized into readable strings that surface ClickUp err/ECODE details and rate-limit guidance.
• stdio-only transport. No HTTP/SSE and no logging to stdout — the standard input/ output channel is the MCP protocol channel.

Available Tools

All 166 tools, grouped by resource. Read tools return either markdown (default) or JSON; mutating tools return a human-readable confirmation.

Tool	Description
Spaces
clickup_create_space	Create a new Space inside a Workspace.
clickup_get_spaces	List the Spaces in a Workspace.
clickup_get_space	Fetch full detail for a single Space, including its status workflow and ClickApp toggles.
clickup_update_space	Rename a Space, change its color/privacy, or replace its ClickApp/status configuration.
clickup_delete_space	Permanently delete a Space and everything inside it.
Folders
clickup_create_folder	Create a Folder inside a Space.
clickup_get_folders	List the Folders in a Space.
clickup_get_folder	Fetch one Folder, including its Lists and status workflow.
clickup_update_folder	Rename a Folder and/or toggle its status-override setting.
clickup_delete_folder	Permanently delete a Folder and every List/Task inside it.
clickup_create_folder_from_template	Create a new Folder by replaying a Folder template.
clickup_get_folder_templates	List the Folder templates available in a Workspace.
Lists
clickup_create_list	Create a new List inside a Folder.
clickup_create_folderless_list	Create a new List directly inside a Space, with no parent Folder.
clickup_get_lists	List the Lists that belong to a Folder.
clickup_get_folderless_lists	List the Lists that live directly inside a Space (no Folder).
clickup_get_list	Fetch full detail for a single List by id.
clickup_update_list	Update a List's name, description, dates, priority, assignee, or color.
clickup_delete_list	Permanently delete a List from the Workspace.
clickup_add_task_to_list	Add an existing Task's membership to an additional List.
clickup_remove_task_from_list	Remove a Task's membership from an additional (non-home) List.
clickup_create_list_from_template_in_folder	Create a new List inside a Folder by instantiating a List template.
clickup_create_list_from_template_in_space	Create a new folderless List inside a Space by instantiating a template.
clickup_get_list_templates	List available List templates for a Workspace.
Views
clickup_create_team_view	Create a task or page view at the Everything Level of a Workspace.
clickup_create_space_view	Create a task or page view scoped to a Space.
clickup_create_folder_view	Create a task or page view scoped to a Folder.
clickup_create_list_view	Create a task or page view scoped to a List.
clickup_get_team_views	List the task and page views defined at the Everything Level of a Workspace.
clickup_get_space_views	List the task and page views available for a Space.
clickup_get_folder_views	List the task and page views available for a Folder.
clickup_get_list_views	List the task and page views available for a List.
clickup_get_view	Get the full configuration of a single task or page view.
clickup_get_view_tasks	List the tasks currently visible in a view, honoring its filters and sorting.
clickup_update_view	Rename a view and/or replace its grouping/sorting/filters/columns/settings.
clickup_delete_view	Permanently delete a task or page view.
Docs
clickup_search_docs	Search the Docs in a Workspace, optionally filtered by parent location.
clickup_create_doc	Create a Doc, optionally placed directly in its final location.
clickup_get_doc	Fetch a single Doc's metadata (name, parent, timestamps).
clickup_get_doc_page_listing	List a Doc's page tree (titles and ids only, nested — no content).
clickup_get_doc_pages	Fetch a Doc's pages with content (the full readable body of the Doc).
clickup_create_page	Add a page to an existing Doc (optionally nested under another page).
clickup_get_page	Fetch one page of a Doc, including its content.
clickup_edit_page	Update a Doc page's title, subtitle, and/or content.
Tasks
clickup_create_task	Create a task inside a List.
clickup_get_task	Fetch one task by id.
clickup_get_tasks	List tasks inside ONE List, with filters and sorting.
clickup_update_task	Update fields on an existing task.
clickup_delete_task	Permanently delete a task.
clickup_get_filtered_team_tasks	Search tasks across the ENTIRE Workspace with rich filters.
clickup_move_task	Move a task to a new home List.
clickup_merge_tasks	Merge one or more source tasks into a target task.
clickup_create_task_from_template	Create a task in a List from a saved task template.
clickup_get_task_templates	List the Workspace's saved task templates.
clickup_get_task_time_in_status	Report how long one task has spent in each status.
clickup_get_bulk_tasks_time_in_status	Report time-in-status for 2 to 100 tasks in one call.
Comments
clickup_create_task_comment	Add a comment to a task.
clickup_get_task_comments	List comments on a task, newest first.
clickup_create_list_comment	Add a comment to a List's info panel.
clickup_get_list_comments	List comments on a List's info panel, newest first.
clickup_create_chat_view_comment	Post a comment into a Chat view.
clickup_get_chat_view_comments	List comments in a Chat view, newest first.
clickup_update_comment	Edit a comment's text, (re)assign it, or toggle its resolved state.
clickup_delete_comment	Permanently delete a comment.
clickup_create_threaded_comment	Reply inside an existing comment's thread.
clickup_get_threaded_comments	List the replies in a comment's thread.
Checklists
clickup_create_checklist	Add a new (empty) checklist to a task.
clickup_edit_checklist	Rename a checklist and/or reposition it among a task's other checklists.
clickup_delete_checklist	Permanently remove a checklist (and all of its items) from its task.
clickup_create_checklist_item	Add a new line item to an existing checklist.
clickup_edit_checklist_item	Rename, (un)resolve, reassign, or nest/un-nest a checklist item.
clickup_delete_checklist_item	Remove a single line item from a checklist (the checklist itself stays).
Tags
clickup_get_space_tags	List every task Tag defined in a Space, with its foreground/background colors.
clickup_create_space_tag	Add a new task Tag (with optional colors) to a Space's tag palette.
clickup_edit_space_tag	Rename and/or recolor an existing Space tag.
clickup_delete_space_tag	Remove a tag from a Space's palette (and from every task carrying it).
clickup_add_tag_to_task	Apply an existing Space tag to a task.
clickup_remove_tag_from_task	Remove a tag from a task without deleting the tag from the Space.
Custom Fields
clickup_get_list_custom_fields	List the Custom Fields accessible from a List.
clickup_get_folder_custom_fields	List the Custom Fields available at a Folder scope.
clickup_get_space_custom_fields	List the Custom Fields available at a Space scope.
clickup_get_team_custom_fields	List the Workspace-scoped Custom Fields.
clickup_set_custom_field_value	Set a Custom Field's value on a task.
clickup_remove_custom_field_value	Clear a Custom Field's value on a task.
clickup_get_custom_task_types	List the Workspace's custom task types (a.k.a. custom items).
Time Tracking
clickup_get_time_entries	List time entries in a Workspace, optionally scoped by date range and location.
clickup_get_time_entry	Fetch one time entry by id.
clickup_get_time_entry_history	View the list of changes made to a time entry.
clickup_get_running_time_entry	Get the currently running time entry for a user, if any.
clickup_create_time_entry	Log a completed (already-finished) time entry.
clickup_update_time_entry	Edit an existing time entry's description, tags, times, task, or billable flag.
clickup_delete_time_entry	Permanently delete one or more time entries.
clickup_start_time_entry	Start a new, open-ended running timer for the authenticated user.
clickup_stop_time_entry	Stop the authenticated user's currently running timer.
clickup_get_time_entry_tags	List every tag ever applied to a time entry in this Workspace.
clickup_add_time_entry_tags	Apply one or more tags to one or more time entries.
clickup_remove_time_entry_tags	Remove one or more tags from one or more time entries.
clickup_rename_time_entry_tag	Rename a time-entry tag (and set its colors) across the whole Workspace.
clickup_replace_time_estimates_by_user	Overwrite a task's entire set of per-assignee time estimates.
clickup_update_time_estimates_by_user	Set or adjust specific assignees' time estimates on a task, leaving others unchanged.
Relationships
clickup_add_dependency	Create a blocking dependency between two tasks.
clickup_delete_dependency	Remove a blocking dependency edge between two tasks.
clickup_add_task_link	Link two tasks with a non-blocking "related to" association.
clickup_delete_task_link	Remove a "related to" link between two tasks.
Attachments
clickup_create_task_attachment	Upload a local file to a task as an attachment (v2).
clickup_get_entity_attachments	List the attachments of a task or File-type Custom Field (v3).
clickup_create_entity_attachment	Upload a local file to a task or File-type Custom Field (v3).
Goals
clickup_create_goal	Create a new Goal in a Workspace.
clickup_get_goals	List the Goals in a Workspace, including any Goal Folders.
clickup_get_goal	Get a single Goal's full detail, including its Key Results.
clickup_update_goal	Update an existing Goal's name, due date, description, owners, or color.
clickup_delete_goal	Permanently delete a Goal and all of its Key Results.
clickup_create_key_result	Add a Key Result (Target) to a Goal.
clickup_edit_key_result	Update a Key Result's progress, note, name, owners, or task/list links.
clickup_delete_key_result	Permanently delete a Key Result (Target) from its Goal.
Members & Groups
clickup_get_list_members	List the Workspace members with direct access to a List.
clickup_get_task_members	List the Workspace members with direct access to a Task.
clickup_create_user_group	Create a User Group (ClickUp's endpoint calls this a "Team") in a Workspace.
clickup_get_user_groups	List the User Groups in a Workspace (ClickUp's endpoint slug: "getteams1").
clickup_update_user_group	Rename a User Group and/or add/remove its members.
clickup_delete_user_group	Permanently delete a User Group from a Workspace.
clickup_get_custom_roles	List the Custom Roles configured for a Workspace.
clickup_get_shared_hierarchy	List the Tasks, Lists, and Folders individually shared with the caller.
Guests (Enterprise)
clickup_invite_guest_to_workspace	Invite an external guest to a Workspace by email.
clickup_edit_guest_on_workspace	Update an existing guest's permission flags or custom role on a Workspace.
clickup_get_guest	Look up a guest's permission flags and what has been shared with them.
clickup_remove_guest_from_workspace	Revoke a guest's access to an entire Workspace.
clickup_add_guest_to_task	Share a single task with an existing guest at a given permission level.
clickup_remove_guest_from_task	Revoke a guest's access to a single task.
clickup_add_guest_to_list	Share a List with an existing guest at a given permission level.
clickup_remove_guest_from_list	Revoke a guest's access to a List.
clickup_add_guest_to_folder	Share a Folder with an existing guest at a given permission level.
clickup_remove_guest_from_folder	Revoke a guest's access to a Folder.
Users (Enterprise)
clickup_invite_user_to_workspace	Invite a full member to a Workspace by email.
clickup_edit_user_on_workspace	Update a Workspace member's username, admin flag, or custom role.
clickup_get_user	Look up a single Workspace member's profile, role, and admin status.
clickup_remove_user_from_workspace	Deactivate a full member's access to a Workspace.
Webhooks
clickup_create_webhook	Register a webhook that pushes ClickUp events to your endpoint.
clickup_get_webhooks	List the webhooks registered in a Workspace, with their delivery health.
clickup_update_webhook	Change a webhook's endpoint, event subscription, or delivery status.
clickup_delete_webhook	Permanently delete a webhook, stopping all event delivery to its endpoint.
Workspace
clickup_get_workspace_plan	Report the current subscription plan of a Workspace.
clickup_get_workspace_seats	Report used, total, and available member and guest seats for a Workspace.
clickup_query_audit_logs	Query a Workspace's audit trail (Enterprise, Workspace owner only).
clickup_update_privacy_and_access	Set the privacy of an object and grant/revoke user or group access (Enterprise).
Chat Channels
clickup_get_chat_channels	List the Chat channels in a Workspace, with descriptor filters.
clickup_create_chat_channel	Create a Workspace-level Chat channel by name.
clickup_create_location_chat_channel	Create a Chat channel bound to a Space, Folder, or List.
clickup_create_direct_message	Create (or return) a direct-message Chat channel with up to 15 users.
clickup_get_chat_channel	Fetch a single Chat channel's metadata by id.
clickup_update_chat_channel	Update a Chat channel's name, description, topic, visibility, or location.
clickup_delete_chat_channel	Permanently delete a Chat channel (Channel, DM, or location-bound).
clickup_get_chat_channel_followers	List the users following a Chat channel.
clickup_get_chat_channel_members	List the users who are members of a Chat channel.
Chat Messages
clickup_get_chat_messages	List the messages in a Chat channel (newest first), cursor-paginated.
clickup_get_chat_message_replies	List the replies threaded under a Chat message, cursor-paginated.
clickup_get_chat_message_reactions	List the emoji reactions on a Chat message, cursor-paginated.
clickup_get_chat_message_tagged_users	List the users @-tagged (mentioned) in a Chat message, cursor-paginated.
clickup_get_chat_subtypes	List a Workspace's post subtype IDs (Announcement, Discussion, Idea, Update).
clickup_send_chat_message	Post a new message to a Chat channel.
clickup_send_chat_reply	Post a threaded reply under an existing Chat message.
clickup_update_chat_message	Edit a Chat message's content, assignee, or resolved state.
clickup_delete_chat_message	Permanently delete a Chat message (and its replies).
clickup_add_chat_reaction	Add an emoji reaction to a Chat message.
clickup_delete_chat_reaction	Remove an emoji reaction from a Chat message.
Health
clickup_health_check	Verify connectivity and authentication against the ClickUp API.

Prerequisites

• Python 3.13+ (only needed for the clone/manual path — uvx and Docker bring their own runtime).
• uv — used for both the zero-install uvx path and local development.
• A ClickUp API token. A personal token (Settings → Apps → API Token, starts with pk_) or an OAuth2 access token. See Authentication.
• (Optional) Your Workspace (team) id if you want tools to default team_id without passing it every call.
• (Optional) Docker if you prefer the container path.

Quickstart

git clone https://github.com/trustxai/clickup-mcp.git
cd clickup-mcp
uv sync --group dev
cp .env.example .env          # then set CLICKUP_API_TOKEN (and optionally CLICKUP_TEAM_ID)
uv run amazing-clickup-mcp    # starts the stdio server

The server speaks MCP over stdio, so it is normally launched by an MCP client (see Client Configuration) rather than run by hand — but launching it directly is a quick way to confirm it imports and starts.

Run with uvx (zero install)

No clone, no virtualenv — uvx fetches and runs the published package in one step:

CLICKUP_API_TOKEN=pk_your_token_here uvx amazing-clickup-mcp

Use amazing-clickup-mcp, not clickup-mcp. The bare clickup-mcp name on PyPI is an unrelated squatter package and will not run this server.

Client Configuration

Every client launches the server as a subprocess and passes credentials through env. Replace pk_your_token_here with your token and, optionally, your_workspace_id with your Workspace (team) id.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "clickup": {
      "command": "uvx",
      "args": ["amazing-clickup-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_token_here",
        "CLICKUP_TEAM_ID": "your_workspace_id"
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config; on macOS it lives at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "clickup": {
      "command": "uvx",
      "args": ["amazing-clickup-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_token_here",
        "CLICKUP_TEAM_ID": "your_workspace_id"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

Register the server with a single command:

claude mcp add clickup \
  --env CLICKUP_API_TOKEN=pk_your_token_here \
  --env CLICKUP_TEAM_ID=your_workspace_id \
  -- uvx amazing-clickup-mcp

Or add the equivalent block to ~/.claude.json under mcpServers (same shape as the Cursor example above).

MCP Inspector

Exercise the server interactively with the official inspector:

CLICKUP_API_TOKEN=pk_your_token_here \
  npx @modelcontextprotocol/inspector uvx amazing-clickup-mcp

If you cloned the repo, you can instead run uv run mcp dev src/clickup_mcp/server.py (the mcp dev CLI ships in the dev dependency group).

Docker

Build the image from the repo Dockerfile, then point any client at docker run:

docker build -t amazing-clickup-mcp .

{
  "mcpServers": {
    "clickup": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CLICKUP_API_TOKEN",
        "-e", "CLICKUP_TEAM_ID",
        "amazing-clickup-mcp"
      ],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_token_here",
        "CLICKUP_TEAM_ID": "your_workspace_id"
      }
    }
  }
}

The -i flag is required — the server communicates over stdin/stdout. The -e NAME entries forward the client-provided env values into the container.

Authentication

The server authenticates with a single ClickUp token, sent verbatim in the Authorization header on every request:

• Personal API token — ClickUp → Settings → Apps → API Token. Starts with pk_. Simplest option; scoped to your own account and permissions.
• OAuth2 access token — for a multi-user integration. Supply the access token you obtained from the OAuth flow.

The token is read from CLICKUP_API_TOKEN (via .env or the client's env block). It is never logged. Missing or invalid credentials fail lazily at the first API call with a clear 401 message rather than at startup.

Environment Variables

Variable	Required	Default	Description
CLICKUP_API_TOKEN	yes	—	Personal API token (pk_…) or OAuth2 access token. Sent verbatim in the Authorization header.
CLICKUP_TEAM_ID	no	—	Default Workspace (team) id used when a call omits team_id.
CLICKUP_API_URL	no	https://api.clickup.com/api/v2	v2 API base URL. Override only for a proxy or testing.
CLICKUP_API_URL_V3	no	https://api.clickup.com/api/v3	v3 API base URL (Docs, Chat, entity attachments, ACL).
CLICKUP_REQUEST_TIMEOUT_SECONDS	no	30	Per-request HTTP timeout, in seconds.

All variables are optional at import time (the server starts without them); only CLICKUP_API_TOKEN is required to make a successful API call.

Running Manually

Once dependencies are installed (uv sync), any of these start the same stdio server:

uv run amazing-clickup-mcp     # console script (recommended)
uv run python -m clickup_mcp    # module entry point

With the package installed into the active environment, amazing-clickup-mcp and python -m clickup_mcp work without the uv run prefix.

Troubleshooting

• 429 Too Many Requests / rate limiting. ClickUp caps requests at roughly 100 requests per minute per token. If you hit a 429, slow down and retry after a short pause; the error message surfaces ClickUp's rate-limit details. Prefer bulk/filtered tools (e.g. clickup_get_filtered_team_tasks, clickup_get_bulk_tasks_time_in_status) over many single-item calls.
• 403 on Guests / Users / Audit logs / ACL. These endpoints are Enterprise-plan only and return 403 on other plans. Affected tools include the clickup_*_guest_* and clickup_*_user_* families, clickup_query_audit_logs, and clickup_update_privacy_and_access. There is no workaround short of an Enterprise plan.
• 403 when adding/removing tasks across Lists. clickup_add_task_to_list and clickup_remove_task_from_list require the Tasks in Multiple Lists ClickApp to be enabled for the Workspace (Settings → ClickApps). Without it the API returns 403.
• v3 cursor pagination. Chat, Docs search, and similar v3 list tools page with an opaque cursor, not offset. Read next_cursor from a response and pass it back as the cursor argument to fetch the next page; repeat until no cursor is returned.
• uvx clickup-mcp runs the wrong thing. The bare clickup-mcp PyPI name is an unrelated package. This server is published as amazing-clickup-mcp — always uvx amazing-clickup-mcp.
• 401 Unauthorized at first call. The token is missing, malformed, or lacks access. Confirm CLICKUP_API_TOKEN is set in the client's env (or .env) and that it is a valid personal (pk_…) or OAuth2 token. Run clickup_health_check to verify.

Contributing

Conventional Commits drive releases (release-please). Before pushing, run the full gate — it must exit 0:

uv run pytest -m "not live" && uv run ruff check src/ && uv run ruff format --check src/ && uv run mypy src/

License

Apache-2.0