io.github.cvrt-jh/clickup-mcp
Lightweight ClickUp MCP server - 37 tools, token-optimized (95% smaller responses)
Open source Open in the app JSON README (API)
About
Lightweight ClickUp MCP server - 37 tools, token-optimized (95% smaller responses)
Details
- Kind
- MCP servers
- Topic
- Productivity
- Publisher
- cvrt-jh
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.3
- Stars
- 3
- Forks
- 1
- Last push
- 2026-08-12T14:58:22Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:38
- Updated
- 2026-08-29 03:02:38
- Origin id
io.github.cvrt-jh/clickup-mcp
README
# clickup-mcp
[](https://www.npmjs.com/package/@cavort-it-systems/clickup-mcp)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
Lightweight ClickUp MCP server focused on task management. 39 tools with **token-optimized responses** - API responses automatically slimmed from thousands of characters to essentials.
## Why This Server?
ClickUp's API returns extremely verbose JSON. This server strips it down:
| Response | Before | After | Reduction |
|----------|--------|-------|-----------|
| `clickup_whoami` | ~3,500 chars | ~160 chars | **95%** |
| `clickup_create_comment` | ~1,500 chars | ~38 chars | **97%** |
Less tokens = faster responses, lower costs, more context for your AI.
## Installation
```bash
npm install -g @cavort-it-systems/clickup-mcp
```
Or run directly:
```bash
npx @cavort-it-systems/clickup-mcp
```
## Configuration
### Claude Code CLI
```bash
claude mcp add clickup -e CLICKUP_API_TOKEN=your-token -- npx @cavort-it-systems/clickup-mcp
```
### Claude Desktop / Manual
Add to your MCP config (`~/.claude.json` or Claude Desktop settings):
```json
{
"mcpServers": {
"clickup": {
"command": "npx",
"args": ["@cavort-it-systems/clickup-mcp"],
"env": {
"CLICKUP_API_TOKEN": "your-token"
}
}
}
}
```
### From Source
```bash
git clone https://github.com/cvrt-jh/clickup-mcp.git
cd clickup-mcp
npm install && npm run build
```
Then configure with the built path:
```bash
claude mcp add clickup -e CLICKUP_API_TOKEN=your-token -- node /path/to/clickup-mcp/build/index.js
```
## Get Your API Token
1. Go to ClickUp Settings > Apps
2. Generate a Personal API Token
3. Set as `CLICKUP_API_TOKEN`
## Response Slimming
All responses are automatically trimmed to save tokens. The ClickUp API returns extremely verbose JSON - this server strips it down to what matters.
**`clickup_whoami`** - from ~3,500 chars to ~160:
```json
// Before (ClickUp API raw)
{"user":{"id":12345678,"username":"Jane Doe","email":"jane@example.com","color":"#0388d1",
"profilePicture":"https://attachments.clickup.com/...","initials":"JD",
"week_start_day":1,"global_font_support":true,"timezone":"Europe/Berlin"},
"teams":{"teams":[{"id":"99999999","name":"My Workspace","color":"#40BC86",
"avatar":"https://attachments2.clickup.com/...?Expires=...&Key-Pair-Id=...&Signature=...",
"members":[{"user":{"id":11111111,"username":"Bob Smith","email":"bob@example.com",
"color":"#aa2fff","profilePicture":null,"initials":"BS","role":4,"role_subtype":2,
"role_key":"guest","custom_role":null,"last_active":"...","date_joined":"...",
"date_invited":"..."},"invited_by":{"id":22222222,...},
"can_see_time_spent":true,...}, ...]}]}}
// After (slimmed)
{"id":12345678,"username":"Jane Doe","email":"jane@example.com",
"timezone":"Europe/Berlin","workspaces":[{"id":"99999999",
"name":"My Workspace","member_count":4}]}
```
**`clickup_create_comment`** - from ~1,500 chars to 38:
```json
// Before
{"id":90150191300876,"hist_id":"...","date":1770053982842,
"version":{"object_type":"comment","object_id":"...","workspace_id":99999999,
"operation":"c","data":{"context":{"root_parent_type":1,"is_chat":false,
"audit_context":{"userid":12345678,"current_time":...,"route":"*"},...},...},...}}
// After
{"id":90150191300876,"date":1770053982842}
```
**What gets stripped:**
| Field | Where | Why |
|-------|-------|-----|
| `features{}` | spaces | ~50 lines of boolean flags per space |
| `sharing{}`, `permission_level` | tasks | Internal access config, not useful |
| `watchers[]` | tasks | Usually same as assignees |
| Full user objects | everywhere | Reduced to `{id, username, email}` |
| `profilePicture`, `initials`, `color` | users | Visual metadata, not useful for LLMs |
| `version{}` blobs | comment/reply creates | Internal versioning data |
| `invited_by`, `profileInfo` | members | Invitation metadata |
| Pretty-print JSON | all responses | Compact single-line output |
| Empty arrays | tasks | `checklists`, `dependencies`, `custom_fields` omitted when empty |
## Tools (37)
### Navigation (7)
- `clickup_whoami` - Current user + workspaces
- `clickup_get_spaces` - Spaces in workspace
- `clickup_get_folders` - Folders in space
- `clickup_get_lists` - Lists in folder or space
- `clickup_get_list` - Single list details
- `clickup_create_list` - Create list in folder or space
- `clickup_delete_list` - Delete a list (permanent)
### Task CRUD (5)
- `clickup_get_task` - Get task by ID
- `clickup_create_task` - Create task with all fields
- `clickup_update_task` - Update any task field
- `clickup_get_tasks` - List tasks in a list
- `clickup_search_tasks` - Search tasks across workspace
### Custom Fields (1)
- `clickup_set_custom_field` - Set custom field value
### Tags (6)
- `clickup_get_space_tags` - List space tags
- `clickup_create_space_tag` - Create tag
- `clickup_edit_space_tag` - Edit tag
- `clickup_delete_space_tag` - Delete tag
- `clickup_add_tag_to_task` - Tag a task
- `clickup_remove_tag_from_task` - Untag a task
### Checklists (6)
- `clickup_create_checklist` - Create checklist
- `clickup_edit_checklist` - Edit checklist
- `clickup_delete_checklist` - Delete checklist
- `clickup_create_checklist_item` - Add item
- `clickup_edit_checklist_item` - Edit item
- `clickup_delete_checklist_item` - Delete item
### Dependencies (4)
- `clickup_add_dependency` - Add dependency
- `clickup_delete_dependency` - Remove dependency
- `clickup_add_task_link` - Link tasks
- `clickup_delete_task_link` - Unlink tasks
### Comments (5)
- `clickup_create_comment` - Add comment
- `clickup_get_comments` - Get comments
- `clickup_update_comment` - Edit/resolve comment
- `clickup_create_reply` - Threaded reply
- `clickup_get_replies` - Get replies
### Delete Task (1)
- `clickup_delete_task` - Delete a task
### Multi-List Membership (2)
- `clickup_add_task_to_list` - Add a task to an **additional** list (multi-homing)
- `clickup_remove_task_from_list` - Remove a task from an additional list
> **These do not move a task.** The ClickUp v2 API has no move-between-lists
> endpoint. Verified against the live API 2026-08-12: `POST /list/{list}/task/{task}`
> adds a secondary location and leaves the home list unchanged, while a `list_id`
> in `PUT /task/{id}` returns HTTP 200 and is silently ignored. To genuinely move a
> task and keep its custom ID and history, use the ClickUp web UI (right-click ->
> Move). Multi-list membership also requires the paid Tasks-in-Multiple-Lists feature.
### Workspace Members (2)
- `clickup_get_workspace_members` - All workspace members
- `clickup_get_list_members` - List-specific members
## Architecture
```
src/
index.ts # Entry: McpServer + StdioServerTransport
client.ts # ClickUp API v2 fetch wrapper
types.ts # Shared Zod schemas + jsonResult helper
slim.ts # Response slimming transformers
tools/
navigation.ts # 7 tools
tasks.ts # 9 tools (CRUD + custom fields + delete + multi-list)
tags.ts # 6 tools
checklists.ts # 6 tools
dependencies.ts # 4 tools
comments.ts # 5 tools
members.ts # 2 tools
```
## License
MIT