Content
# ClickUp MCP Server (amazing-clickup-mcp)
A comprehensive [Model Context Protocol](https://modelcontextprotocol.io) server for the
[ClickUp public API](https://developer.clickup.com/reference) (v2 + v3), built on the
official [MCP Python SDK](https://github.com/modelcontextprotocol/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](https://docs.astral.sh/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](#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
```bash
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](#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:
```bash
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):
```json
{
"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`):
```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:
```bash
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:
```bash
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`:
```bash
docker build -t amazing-clickup-mcp .
```
```json
{
"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:
```bash
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`:
```bash
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](LICENSE)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available