clickup-full-mcp 0.0.0-stage → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,46 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
5
+
6
+ ## [Unreleased]
7
+
8
+ ## [2.0.0] - 2026-11-20
9
+
10
+ ### Changed
11
+
12
+ - **Breaking: meta mode is now the default.** With no `CLICKUP_TOOL_MODE` set, the server exposes 4 tools that reach all 173 operations (~700 tokens of context). Set `CLICKUP_TOOL_MODE=full` for the previous behaviour of one tool per endpoint.
13
+
14
+ ### Added
15
+
16
+ - Published to npm: run with `npx -y clickup-full-mcp`.
17
+ - Listed in the official MCP Registry as `io.github.KelvinCampelo/clickup-full-mcp` (`server.json`).
18
+ - Release workflow publishes to npm with provenance (trusted publishing) and to the MCP Registry on every version tag.
19
+
20
+ ## [1.0.0] - 2026-11-20
21
+
22
+ First public release.
23
+
24
+ ### Added
25
+
26
+ - MCP server (stdio) exposing all 173 ClickUp API operations (v2 + v3) as tools, generated from ClickUp's official OpenAPI specs.
27
+ - `meta` mode: 4 tools (`clickup_search_operations`, `clickup_describe_operation`, `clickup_call_operation`, `clickup_request`) that reach every operation for ~700 tokens of context, and `full` mode with one tool per endpoint.
28
+ - Operation search ranks name matches above summary, path and description matches, and understands everyday verbs ("log time" → `create_time_entry`, "post message" → `send_chat_message`).
29
+ - Filters: `CLICKUP_TOOLSETS`, `CLICKUP_READ_ONLY`, `CLICKUP_DISABLED_TOOLS`.
30
+ - `clickup_request` raw tool for any `/api/v2` or `/api/v3` path.
31
+ - Default workspace (`CLICKUP_WORKSPACE_ID`) auto-filled into `team_id` / `workspace_id`.
32
+ - File uploads from a local path or base64, optionally restricted with `CLICKUP_UPLOAD_ROOTS`.
33
+ - 429 retries honouring `Retry-After` / `X-RateLimit-Reset`; request timeouts; large-response truncation.
34
+ - Personal tokens and OAuth access tokens (sent as `Bearer`), plus `get_access_token` for the OAuth code exchange.
35
+ - `--version` flag.
36
+ - Generated tool reference in `docs/tools/` (one page per toolset, with arguments and body fields), kept in sync with the specs by `npm run generate` and CI.
37
+
38
+ ### Security
39
+
40
+ - `clickup_request` normalizes paths before checking them, so `..`, `%2e%2e` and backslash traversal can't leave `/api/v2` / `/api/v3`.
41
+ - `CLICKUP_UPLOAD_ROOTS` checks resolve symlinks, so a link inside an allowed folder can't expose files outside it.
42
+ - Invalid numeric or URL settings now fail at startup with a clear message instead of misbehaving at runtime.
43
+
44
+ [Unreleased]: https://github.com/KelvinCampelo/clickup-full-mcp/compare/v2.0.0...HEAD
45
+ [2.0.0]: https://github.com/KelvinCampelo/clickup-full-mcp/compare/v1.0.0...v2.0.0
46
+ [1.0.0]: https://github.com/KelvinCampelo/clickup-full-mcp/releases/tag/v1.0.0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kelvin Campelo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE ADDED
@@ -0,0 +1,17 @@
1
+ clickup-full-mcp
2
+ Copyright (c) 2026 Kelvin Campelo. Licensed under the MIT License (see LICENSE).
3
+
4
+ This is an independent, community project. It is not affiliated with, endorsed
5
+ by, or sponsored by ClickUp. "ClickUp" is a trademark of its owner and is used
6
+ here only to describe the API this software talks to.
7
+
8
+ Third-party material
9
+ --------------------
10
+
11
+ spec/clickup-api-v2-reference.json
12
+ spec/ClickUp_PUBLIC_API_V3.yaml
13
+ ClickUp's public OpenAPI specifications, as published at
14
+ https://developer.clickup.com/. They are included unmodified so that the
15
+ generated tool definitions are reproducible, remain the property of ClickUp,
16
+ and are NOT covered by this project's MIT license. src/generated/operations.json
17
+ is derived from them by scripts/generate.mjs.
package/README.md CHANGED
@@ -1,3 +1,369 @@
1
- # Temporary Holding Version
1
+ # ClickUp MCP Server (clickup-full-mcp)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/clickup-full-mcp.svg)](https://www.npmjs.com/package/clickup-full-mcp)
4
+ [![CI](https://github.com/KelvinCampelo/clickup-full-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/KelvinCampelo/clickup-full-mcp/actions/workflows/ci.yml)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
7
+ [![MCP](https://img.shields.io/badge/MCP-stdio-8A2BE2.svg)](https://modelcontextprotocol.io)
8
+
9
+ **The entire ClickUp API in 4 tools.** A local [Model Context Protocol](https://modelcontextprotocol.io) 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.
10
+
11
+ 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.
12
+
13
+ > [!NOTE]
14
+ > Community project, not affiliated with or endorsed by ClickUp.
15
+
16
+ ## Contents
17
+
18
+ - [Why 4 tools?](#why-4-tools)
19
+ - [Features](#features)
20
+ - [Quick start](#quick-start)
21
+ - [Client setup](#client-setup): Claude Desktop, Claude Code, Cursor, VS Code, others
22
+ - [Common ClickUp operations](#common-clickup-operations): examples you can copy
23
+ - [Configuration](#configuration)
24
+ - [How tools map to the API](#how-tools-map-to-the-api) · **[Full tool reference →](docs/tools/README.md)**
25
+ - [Security](#security)
26
+ - [Troubleshooting](#troubleshooting)
27
+ - [FAQ](#faq)
28
+ - [Contributing](#contributing)
29
+
30
+ ## Why 4 tools?
31
+
32
+ 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.
33
+
34
+ By default this server exposes just 4 tools that reach the whole API:
35
+
36
+ | Tool | What it does |
37
+ | ---------------------------- | -------------------------------------------------------------------------------------- |
38
+ | `clickup_search_operations` | Finds operations by keyword: "create task", "log time", "send chat message"… |
39
+ | `clickup_describe_operation` | Returns one operation's full description and JSON input schema, only when it's needed. |
40
+ | `clickup_call_operation` | Calls any of the 173 operations by name. |
41
+ | `clickup_request` | Raw escape hatch for any `/api/v2` or `/api/v3` path. |
42
+
43
+ Measured `tools/list` size (v1.0.0, tokens ≈ characters ÷ 4):
44
+
45
+ | Mode | Tools | Schema size | Context cost |
46
+ | -------------------------------------------------------- | ----: | ----------: | ------------------------ |
47
+ | `full` (`CLICKUP_TOOL_MODE=full`) | 174 | 214 KB | **~55,000 tokens** |
48
+ | `full` + `CLICKUP_TOOLSETS=tasks,comments,time_tracking` | 42 | 61 KB | ~15,600 tokens |
49
+ | **`meta` (default)** | **4** | **2.6 KB** | **~700 tokens** (−98.8%) |
50
+
51
+ A typical meta-mode exchange costs one or two extra small calls, and the model only ever loads the schemas it actually uses:
52
+
53
+ ```jsonc
54
+ // 1. Find the operation
55
+ clickup_search_operations { "query": "create task" }
56
+ // → [{ "name": "create_task", "http": "POST /api/v2/list/{list_id}/task", … }, …]
57
+
58
+ // 2. (optional) Read its schema
59
+ clickup_describe_operation { "name": "create_task" }
60
+
61
+ // 3. Call it, with the same arguments as the full-mode tool
62
+ clickup_call_operation { "name": "create_task", "arguments": { "list_id": "901", "body": { "name": "Ship MCP" } } }
63
+ ```
64
+
65
+ Search understands everyday wording: "log time" finds `create_time_entry`, "find tasks" finds `get_tasks`, "post message" finds `send_chat_message`.
66
+
67
+ 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`.
68
+
69
+ ## Features
70
+
71
+ - **Complete coverage**: 173 operations (138 v2 + 35 v3) with full JSON Schemas for every parameter and request body. See the [tool reference](docs/tools/README.md).
72
+ - **Token-efficient by default**: 4-tool meta mode (~700 tokens), or full mode with per-toolset filtering.
73
+ - **Scoping**: read-only mode, toolset filters, and a deny-list for individual tools like `delete_space`.
74
+ - **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.
75
+ - **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).
76
+ - **Helpful errors**: unknown or misplaced arguments are rejected before any HTTP call, with a hint; ClickUp errors include the HTTP status and `ECODE`.
77
+ - **Local and private**: runs on your machine over stdio. Your token only goes to the ClickUp API.
78
+ - **Always current**: a weekly CI job pulls ClickUp's latest OpenAPI specs and opens a PR when they change.
79
+
80
+ ## Quick start
81
+
82
+ **Requirements:** Node.js 20+.
83
+
84
+ 1. **Get a ClickUp API token**: ClickUp → your avatar → **Settings → Apps → API Token** (starts with `pk_`). OAuth access tokens also work.
85
+ 2. **Add the server to your MCP client** (see [Client setup](#client-setup)). The quickest way runs it straight from GitHub:
86
+
87
+ ```bash
88
+ npx -y clickup-full-mcp
89
+ ```
90
+
91
+ No install step: `npx` fetches the [npm package](https://www.npmjs.com/package/clickup-full-mcp) on first run. The server is also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.KelvinCampelo/clickup-full-mcp) as `io.github.KelvinCampelo/clickup-full-mcp`.
92
+
93
+ 3. **Ask your assistant** something like:
94
+ - "List the open tasks assigned to me in the _Sprint 42_ list."
95
+ - "Create a task in _Backlog_ called 'Ship MCP', priority high, due Friday, with a QA checklist."
96
+ - "Move every task tagged `bug` in _Inbox_ to _Triage_ and comment 'moved by triage bot'."
97
+ - "Log 1h30 on task `86abc123` for today with the note 'code review'."
98
+ - "How many hours did I track this week, per task?"
99
+ - "Summarize this week's messages in the _#engineering_ chat channel."
100
+ - "Create a Doc page 'Release notes v1.2' from the tasks closed this sprint."
101
+
102
+ > [!TIP]
103
+ > For a first run, add `CLICKUP_READ_ONLY=true`. Only GET endpoints are exposed, so nothing can be changed.
104
+
105
+ ### Alternative: run from a local clone
106
+
107
+ ```bash
108
+ git clone https://github.com/KelvinCampelo/clickup-full-mcp.git
109
+ cd clickup-full-mcp
110
+ npm install # also builds dist/
111
+ npm test # optional: end-to-end tests against a mock ClickUp
112
+ ```
113
+
114
+ Then use `"command": "node"` and `"args": ["/ABSOLUTE/PATH/clickup-full-mcp/dist/index.js"]` in the client configs below.
115
+
116
+ ## Client setup
117
+
118
+ 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.
119
+
120
+ <details open>
121
+ <summary><b>Claude Desktop</b></summary>
122
+
123
+ Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):
124
+
125
+ ```json
126
+ {
127
+ "mcpServers": {
128
+ "clickup": {
129
+ "command": "npx",
130
+ "args": ["-y", "clickup-full-mcp"],
131
+ "env": {
132
+ "CLICKUP_API_TOKEN": "pk_xxx",
133
+ "CLICKUP_WORKSPACE_ID": "1234567"
134
+ }
135
+ }
136
+ }
137
+ }
138
+ ```
139
+
140
+ </details>
141
+
142
+ <details>
143
+ <summary><b>Claude Code</b></summary>
144
+
145
+ ```bash
146
+ claude mcp add clickup --scope user \
147
+ -e CLICKUP_API_TOKEN=pk_xxx -e CLICKUP_WORKSPACE_ID=1234567 \
148
+ -- npx -y clickup-full-mcp
149
+ ```
150
+
151
+ </details>
152
+
153
+ <details>
154
+ <summary><b>Cursor</b></summary>
155
+
156
+ `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
157
+
158
+ ```json
159
+ {
160
+ "mcpServers": {
161
+ "clickup": {
162
+ "command": "npx",
163
+ "args": ["-y", "clickup-full-mcp"],
164
+ "env": { "CLICKUP_API_TOKEN": "pk_xxx", "CLICKUP_WORKSPACE_ID": "1234567" }
165
+ }
166
+ }
167
+ }
168
+ ```
169
+
170
+ </details>
171
+
172
+ <details>
173
+ <summary><b>VS Code (GitHub Copilot)</b></summary>
174
+
175
+ `.vscode/mcp.json`. VS Code prompts for the token and stores it securely:
176
+
177
+ ```json
178
+ {
179
+ "inputs": [{ "type": "promptString", "id": "clickup-token", "description": "ClickUp API token", "password": true }],
180
+ "servers": {
181
+ "clickup": {
182
+ "type": "stdio",
183
+ "command": "npx",
184
+ "args": ["-y", "clickup-full-mcp"],
185
+ "env": { "CLICKUP_API_TOKEN": "${input:clickup-token}" }
186
+ }
187
+ }
188
+ }
189
+ ```
190
+
191
+ </details>
192
+
193
+ <details>
194
+ <summary><b>Any other MCP client or agent framework</b></summary>
195
+
196
+ 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.
197
+
198
+ Prefer containers? Build the image from a clone and run it over stdio:
199
+
200
+ ```bash
201
+ docker build -t clickup-full-mcp .
202
+ docker run -i --rm -e CLICKUP_API_TOKEN=pk_xxx clickup-full-mcp
203
+ ```
204
+
205
+ </details>
206
+
207
+ ## Common ClickUp operations
208
+
209
+ 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](docs/tools/README.md).
210
+
211
+ ### Tasks
212
+
213
+ | Goal | Tool | Arguments |
214
+ | ---------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
215
+ | Get tasks in a list, filtered | [`get_tasks`](docs/tools/tasks.md#get_tasks) | `{ "list_id": "901", "statuses": ["to do", "in progress"], "assignees": [183], "include_closed": false }` |
216
+ | Search tasks across the workspace | [`get_filtered_team_tasks`](docs/tools/tasks.md#get_filtered_team_tasks) | `{ "tags": ["bug"], "due_date_lt": 1767225600000, "include_closed": false }` |
217
+ | Get one task with its subtasks | [`get_task`](docs/tools/tasks.md#get_task) | `{ "task_id": "86abc123", "include_subtasks": true }` |
218
+ | Create a task | [`create_task`](docs/tools/tasks.md#create_task) | `{ "list_id": "901", "body": { "name": "Ship MCP", "markdown_content": "**Why:** …", "priority": 2, "due_date": 1767225600000 } }` |
219
+ | Create a subtask | [`create_task`](docs/tools/tasks.md#create_task) | `{ "list_id": "901", "body": { "name": "Write docs", "parent": "86abc123" } }` |
220
+ | Change status, assignees, priority | [`update_task`](docs/tools/tasks.md#update_task) | `{ "task_id": "86abc123", "body": { "status": "in review", "priority": 1, "assignees": { "add": [183], "rem": [] } } }` |
221
+ | Move a task to another list | [`move_task`](docs/tools/tasks.md#move_task) | `{ "task_id": "86abc123", "list_id": "902", "body": {} }` |
222
+ | Delete a task | [`delete_task`](docs/tools/tasks.md#delete_task) | `{ "task_id": "86abc123" }` |
223
+
224
+ ### Comments, checklists, tags, custom fields
225
+
226
+ | Goal | Tool | Arguments |
227
+ | --------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
228
+ | Comment on a task | [`create_task_comment`](docs/tools/comments.md#create_task_comment) | `{ "task_id": "86abc123", "body": { "comment_text": "Deployed to staging", "notify_all": false } }` |
229
+ | Read a task's comments | [`get_task_comments`](docs/tools/comments.md#get_task_comments) | `{ "task_id": "86abc123" }` |
230
+ | Add a checklist | [`create_checklist`](docs/tools/task_checklists.md#create_checklist) | `{ "task_id": "86abc123", "body": { "name": "QA" } }` |
231
+ | Add a checklist item | [`create_checklist_item`](docs/tools/task_checklists.md#create_checklist_item) | `{ "checklist_id": "b955c4dc-…", "body": { "name": "Test on mobile" } }` |
232
+ | Tag a task | [`add_tag_to_task`](docs/tools/tags.md#add_tag_to_task) | `{ "task_id": "86abc123", "tag_name": "bug" }` |
233
+ | List a list's custom fields | [`get_list_custom_fields`](docs/tools/custom_fields.md#get_list_custom_fields) | `{ "list_id": "901" }` |
234
+ | Set a custom field value | [`set_custom_field_value`](docs/tools/custom_fields.md#set_custom_field_value) | `{ "task_id": "86abc123", "field_id": "0a52c486-…", "body": { "value": "https://example.com" } }` |
235
+
236
+ ### Time tracking
237
+
238
+ | Goal | Tool | Arguments |
239
+ | -------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
240
+ | Start a timer | [`start_time_entry`](docs/tools/time_tracking.md#start_time_entry) | `{ "body": { "tid": "86abc123", "description": "code review" } }` |
241
+ | Stop the running timer | [`stop_time_entry`](docs/tools/time_tracking.md#stop_time_entry) | `{}` |
242
+ | Log time after the fact | [`create_time_entry`](docs/tools/time_tracking.md#create_time_entry) | `{ "body": { "tid": "86abc123", "start": 1763625600000, "duration": 5400000, "description": "code review" } }` |
243
+ | Timesheet for a date range | [`get_time_entries_within_date_range`](docs/tools/time_tracking.md#get_time_entries_within_date_range) | `{ "start_date": 1763337600000, "end_date": 1763942400000 }` |
244
+
245
+ ### Workspace structure, Docs and Chat
246
+
247
+ | Goal | Tool | Arguments |
248
+ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
249
+ | List workspaces (find your ID) | [`get_authorized_workspaces`](docs/tools/workspaces.md#get_authorized_workspaces) | `{}` |
250
+ | Browse spaces → folders → lists | [`get_spaces`](docs/tools/spaces.md#get_spaces) → [`get_folders`](docs/tools/folders.md#get_folders) → [`get_lists`](docs/tools/lists.md#get_lists) | `{}` → `{ "space_id": "90120001" }` → `{ "folder_id": "90120002" }` |
251
+ | Lists that aren't in a folder | [`get_folderless_lists`](docs/tools/lists.md#get_folderless_lists) | `{ "space_id": "90120001" }` |
252
+ | List Docs / read a Doc's pages | [`search_docs`](docs/tools/docs.md#search_docs) / [`get_doc_pages`](docs/tools/docs.md#get_doc_pages) | `{}` / `{ "doc_id": "…" }` |
253
+ | Write a Doc page in Markdown | [`create_doc_page`](docs/tools/docs.md#create_doc_page) | `{ "doc_id": "…", "body": { "name": "Release notes", "content": "# v1.2\n…", "content_format": "text/md" } }` |
254
+ | Find a Chat channel | [`get_chat_channels`](docs/tools/chat.md#get_chat_channels) | `{}` |
255
+ | Post a Chat message | [`send_chat_message`](docs/tools/chat.md#send_chat_message) | `{ "channel_id": "…", "body": { "type": "message", "content": "Deploy done ✅" } }` |
256
+ | Anything not covered by a typed tool | `clickup_request` | `{ "method": "GET", "path": "/api/v2/team/1234567/space", "query": { "archived": false } }` |
257
+
258
+ ## Configuration
259
+
260
+ All configuration is through environment variables. See [`.env.example`](.env.example).
261
+
262
+ | Variable | Default | Purpose |
263
+ | -------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------ |
264
+ | `CLICKUP_API_TOKEN` | (none) | Personal token (`pk_…`) or OAuth access token. Required for everything except `get_access_token`. |
265
+ | `CLICKUP_WORKSPACE_ID` | (none) | Default Workspace (team) ID. Auto-fills `team_id` / `workspace_id` and makes them optional in schemas. |
266
+ | `CLICKUP_TOOL_MODE` | `meta` | `meta` = [4 tools for the whole API](#why-4-tools). `full` = one tool per endpoint. |
267
+ | `CLICKUP_TOOLSETS` | all | Comma list of [toolsets](#toolsets) to expose (works in both modes). |
268
+ | `CLICKUP_READ_ONLY` | `false` | Only expose GET operations; `clickup_request` is limited to GET. |
269
+ | `CLICKUP_DISABLED_TOOLS` | (none) | Comma list of operation names to hide, e.g. `delete_space,delete_folder`. |
270
+ | `CLICKUP_ENABLE_RAW_REQUEST` | `true` | Expose `clickup_request` (raw call to any `/api/v2` or `/api/v3` path). |
271
+ | `CLICKUP_UPLOAD_ROOTS` | (none) | Comma list of folders that `file_path` uploads may read from. Unset means any file the user can read. |
272
+ | `CLICKUP_MAX_RESPONSE_CHARS` | `100000` | Truncate very large responses. |
273
+ | `CLICKUP_TIMEOUT_MS` / `CLICKUP_MAX_RETRIES` | `60000` / `3` | Request timeout and 429 retries. |
274
+ | `CLICKUP_BASE_URL` | `https://api.clickup.com` | Override for testing or proxies. The token is sent to this host. |
275
+
276
+ Find your Workspace ID in any ClickUp URL (`app.clickup.com/<workspace_id>/…`), or ask the assistant to run `get_authorized_workspaces`.
277
+
278
+ ### Toolsets
279
+
280
+ Each toolset links to its generated reference page with every tool's arguments and body fields ([index](docs/tools/README.md)).
281
+
282
+ [`attachments`](docs/tools/attachments.md) (3) · [`audit_logs`](docs/tools/audit_logs.md) (1) · [`authorization`](docs/tools/authorization.md) (2) · [`chat`](docs/tools/chat.md) (19) · [`comments`](docs/tools/comments.md) (11) · [`custom_fields`](docs/tools/custom_fields.md) (6) · [`custom_task_types`](docs/tools/custom_task_types.md) (1) · [`docs`](docs/tools/docs.md) (8) · [`folders`](docs/tools/folders.md) (7) · [`goals`](docs/tools/goals.md) (8) · [`guests`](docs/tools/guests.md) (10) · [`lists`](docs/tools/lists.md) (11) · [`members`](docs/tools/members.md) (2) · [`privacy_and_access`](docs/tools/privacy_and_access.md) (1) · [`roles`](docs/tools/roles.md) (1) · [`shared_hierarchy`](docs/tools/shared_hierarchy.md) (1) · [`spaces`](docs/tools/spaces.md) (5) · [`tags`](docs/tools/tags.md) (6) · [`task_checklists`](docs/tools/task_checklists.md) (6) · [`task_relationships`](docs/tools/task_relationships.md) (4) · [`tasks`](docs/tools/tasks.md) (13) · [`templates`](docs/tools/templates.md) (3) · [`time_tracking`](docs/tools/time_tracking.md) (17) · [`user_groups`](docs/tools/user_groups.md) (4) · [`users`](docs/tools/users.md) (4) · [`views`](docs/tools/views.md) (12) · [`webhooks`](docs/tools/webhooks.md) (4) · [`workspaces`](docs/tools/workspaces.md) (3)
283
+
284
+ ## How tools map to the API
285
+
286
+ 📖 **[Tool reference](docs/tools/README.md)**: every tool with its HTTP endpoint, arguments and request-body fields, generated from the OpenAPI specs.
287
+
288
+ - **Tool names** are snake_case versions of the endpoint (`create_task`, `get_tasks`, `send_chat_message`, `get_doc_pages`, …).
289
+ - **Path and query parameters** go at the top level of the arguments.
290
+ - **JSON request bodies** go in `body`:
291
+
292
+ ```json
293
+ { "list_id": "901", "body": { "name": "Ship MCP", "priority": 2, "assignees": [123] } }
294
+ ```
295
+
296
+ - **File uploads** (`create_task_attachment`, `create_attachment`): pass `file_path` (a local file) or `file_base64` + `file_name`.
297
+ - **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`").
298
+ - **Annotations** mark GETs as read-only and DELETEs as destructive, so clients can ask for confirmation.
299
+ - Every tool description ends with its HTTP method and path, e.g. `ClickUp API v2: POST /api/v2/list/{list_id}/task`.
300
+
301
+ ### OAuth (`get_access_token`)
302
+
303
+ 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.
304
+
305
+ ## Security
306
+
307
+ - **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/`.
308
+ - **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.
309
+ - **Uploads read local files.** Set `CLICKUP_UPLOAD_ROOTS` to restrict which folders `file_path` can read. Symlinks are resolved before the check.
310
+ - **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.
311
+
312
+ Found a vulnerability? Please report it privately, see [SECURITY.md](SECURITY.md).
313
+
314
+ ## Troubleshooting
315
+
316
+ | Symptom | Fix |
317
+ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
318
+ | `CLICKUP_API_TOKEN is not set` | Add the token to the `env` block of your client config, then restart the client. |
319
+ | `HTTP 401` | The token is wrong or was regenerated. Copy a fresh one from Settings → Apps. |
320
+ | `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`. |
321
+ | 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. |
322
+ | `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`. |
323
+ | 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. |
324
+ | Response cut off with `[truncated: …]` | Use paging/filters, or raise `CLICKUP_MAX_RESPONSE_CHARS`. |
325
+
326
+ Server logs (one `[clickup-mcp] … ready` line on start, plus warnings) go to stderr, which most clients show in their MCP log view.
327
+
328
+ ## FAQ
329
+
330
+ **Is there an MCP server that covers the whole ClickUp API?**
331
+ 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.
332
+
333
+ **How do I connect ClickUp to Claude, Cursor or VS Code?**
334
+ Add the server to your client's MCP config with your ClickUp API token (see [Client setup](#client-setup)). It runs locally over stdio via `npx -y clickup-full-mcp`; no hosting needed.
335
+
336
+ **How many tokens does it use?**
337
+ 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?](#why-4-tools).
338
+
339
+ **Can it create tasks, track time, comment, and post in ClickUp Chat?**
340
+ 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](#common-clickup-operations).
341
+
342
+ **Can I make it read-only?**
343
+ Yes: `CLICKUP_READ_ONLY=true` exposes only GET operations and blocks writes through `clickup_request`.
344
+
345
+ **Does it work with AI agents and agent SDKs, not just chat apps?**
346
+ 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.
347
+
348
+ **Is it official?**
349
+ No. It's an independent open-source project (MIT) and is not affiliated with ClickUp.
350
+
351
+ ## Keeping up with ClickUp
352
+
353
+ ClickUp's specs are vendored in `spec/`. A weekly GitHub Action downloads the latest versions, regenerates the tools and the [tool reference](docs/tools/README.md), and opens a PR when anything changed. To refresh manually:
354
+
355
+ ```bash
356
+ npm run update-spec && npm run build
357
+ ```
358
+
359
+ 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`).
360
+
361
+ ## Contributing
362
+
363
+ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, project layout and how the generated code works. Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).
364
+
365
+ ## License
366
+
367
+ [MIT](LICENSE) © Kelvin Campelo.
368
+
369
+ ClickUp's OpenAPI specs in `spec/` belong to ClickUp and are included only for reproducible code generation; see [NOTICE](NOTICE). "ClickUp" is a trademark of its owner. This project is not affiliated with ClickUp.