teren-papercutlabs/clickup-mcp
If you are the rightful owner of clickup-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The ClickUp MCP Server integrates ClickUp task management with model context protocol, offering robust task operations, search capabilities, and workspace management.
clickup_create_task
Create a new task with full configuration
clickup_get_task
Get detailed task information
clickup_update_task
Update task properties (partial updates)
clickup_delete_task
Permanently delete a task
clickup_list_tasks
List tasks from a specific list with filters
clickup_search_tasks
Search with flexible scope (workspace/space/folder/list)
clickup_add_comment
Add a comment to a task
clickup_list_comments
Get all comments for a task
clickup_add_dependency
Create task dependency relationship
clickup_remove_dependency
Remove task dependency
clickup_list_dependencies
View all dependencies for a task
clickup_get_workspace_structure
Discover workspace hierarchy
ClickUp MCP Server
MCP server for ClickUp task management integration, providing comprehensive task operations, search capabilities, and workspace management.
Features
- Task Management: Create, read, update, and delete tasks
- Search: Flexible search with scope control (workspace/space/folder/list)
- Comments: Add and list task comments
- Dependencies: Manage task dependencies and relationships
- Workspace Discovery: Navigate workspace hierarchy
Installation
From npm
npm install -g @mcp-servers/clickup
From source
git clone <repository>
cd mcp-servers/clickup
npm install
npm run build
Configuration
Getting your ClickUp API Token
- Log into ClickUp
- Navigate to Settings → Apps
- Under API Token, click "Generate" or copy existing token
- Save your personal API token
Environment Setup
Set the CLICKUP_API_TOKEN
environment variable:
export CLICKUP_API_TOKEN="pk_YOUR_TOKEN_HERE"
MCP Configuration
Add to your MCP settings file (.mcp.json
or equivalent):
{
"servers": {
"clickup": {
"command": "mcp-server-clickup",
"env": {
"CLICKUP_API_TOKEN": "pk_YOUR_TOKEN_HERE"
}
}
}
}
Usage
Core Task Operations
Create Task
clickup_create_task({
list_id: "901234567",
name: "Implement new feature",
markdown_description: "## Description\n- Feature details\n- Implementation notes",
priority: 2, // High
tags: ["feature", "backend"],
assignees: [123456] // User IDs
})
Get Task Details
clickup_get_task({
task_id: "abc123"
})
Update Task
clickup_update_task({
task_id: "abc123",
status: "in progress",
priority: 1, // Urgent
assignees_add: [789012],
tags_add: ["urgent"]
})
List Tasks
clickup_list_tasks({
list_id: "901234567",
page: 0,
include_closed: false,
statuses: ["open", "in progress"]
})
Search Operations
Search with Scope Control
// Search in specific list (fastest)
clickup_search_tasks({
query: "bug",
scope: "list",
list_id: "901234567",
team_id: "123456"
})
// Search entire workspace (broadest)
clickup_search_tasks({
query: "overdue",
scope: "workspace",
team_id: "123456",
due_date_lt: Date.now()
})
Comments
Add Comment
clickup_add_comment({
task_id: "abc123",
comment_text: "Started working on this. ETA 2 hours.",
notify_all: true
})
List Comments
clickup_list_comments({
task_id: "abc123"
})
Dependencies
Add Dependency
// Task A waits for Task B
clickup_add_dependency({
task_id: "taskA",
depends_on: "taskB"
})
// Task C blocks Task D
clickup_add_dependency({
task_id: "taskC",
dependency_of: "taskD"
})
View Dependencies
clickup_list_dependencies({
task_id: "abc123"
})
Workspace Discovery
Get Full Workspace Structure
clickup_get_workspace_structure()
// Returns hierarchy: Teams → Spaces → Lists
Tool Reference
Task Tools
Tool | Description |
---|---|
clickup_create_task | Create a new task with full configuration |
clickup_get_task | Get detailed task information |
clickup_update_task | Update task properties (partial updates) |
clickup_delete_task | Permanently delete a task |
clickup_list_tasks | List tasks from a specific list with filters |
Search Tools
Tool | Description |
---|---|
clickup_search_tasks | Search with flexible scope (workspace/space/folder/list) |
Comment Tools
Tool | Description |
---|---|
clickup_add_comment | Add a comment to a task |
clickup_list_comments | Get all comments for a task |
Dependency Tools
Tool | Description |
---|---|
clickup_add_dependency | Create task dependency relationship |
clickup_remove_dependency | Remove task dependency |
clickup_list_dependencies | View all dependencies for a task |
Workspace Tools
Tool | Description |
---|---|
clickup_get_workspace_structure | Discover workspace hierarchy |
Best Practices
Performance
- Use narrow search scopes: List search is 10x faster than workspace search
- Implement pagination: Use page parameter for large result sets
- Cache workspace structure: It rarely changes
Task Creation
- Always specify
list_id
- tasks must belong to a list - Use
markdown_description
for rich formatting - Set meaningful priorities (1=Urgent, 2=High, 3=Normal, 4=Low)
- Include time estimates in milliseconds when known
Error Handling
The server passes through raw ClickUp API errors, which include:
- Invalid list/task IDs
- Permission errors
- Rate limiting
- Validation errors (e.g., invalid status, missing required fields)
Common Patterns
Find tasks assigned to me
// First, get your user ID from workspace structure
const workspace = await clickup_get_workspace_structure();
// Then search for your tasks
clickup_search_tasks({
query: "",
scope: "workspace",
team_id: workspace.teams[0].id,
assignees: ["your_user_id"]
})
Create task with due date
// Convert natural language to timestamp
const dueDate = new Date("2024-12-31").getTime();
clickup_create_task({
list_id: "901234567",
name: "Year-end report",
due_date: dueDate,
priority: 2
})
Limitations
- Maximum 100 tasks per page in list/search operations
- Custom fields not supported in this version
- Rate limits apply based on your ClickUp plan
- Attachments and time tracking not yet implemented
Development
Building from source
npm install
npm run build
Testing locally
CLICKUP_API_TOKEN=your_token npm run dev
Contributing
Contributions welcome! Please ensure:
- TypeScript types are properly defined
- Tool descriptions include usage guidelines
- Error messages are helpful
- Code follows existing patterns
License
MIT