Provides comprehensive project management capabilities including hierarchical organization (workspaces, spaces, folders, lists, tasks), task management with custom fields, time tracking, goal setting and progress monitoring, team collaboration through comments and assignments, and search functionality across workspaces.
ClickUp MCP Server
MCP server for ClickUp API. Manage projects, tasks, time tracking, goals, and team collaboration with a flexible hierarchical project management system.
Features
Hierarchical Organization: Workspace → Space → Folder → List → Task
Task Management: Create, update, and track tasks with custom fields
Time Tracking: Log time entries and estimates
Goals: Set and track goals with progress metrics
Custom Fields: Flexible metadata for tasks
Collaboration: Comments, assignments, and notifications
Search: Find tasks across your workspace
Statuses: Customizable per-list status workflows
Setup
Prerequisites
ClickUp account (free or paid)
API token
Environment Variables
CLICKUP_API_TOKEN
(required): Your ClickUp API token
How to get credentials:
Go to app.clickup.com
Log in to your account
Click your avatar → Settings
Go to "Apps" in the sidebar
Click "Generate" under "API Token"
Copy the token (starts with
pk_
)Store as
CLICKUP_API_TOKEN
Direct link: https://app.clickup.com/settings/apps
Important: Keep your API token secure. It has full access to your ClickUp account.
Rate Limits
Standard: 100 requests per minute per token
Rate limit headers included in responses
HTTP 429 response when limit exceeded
Consider caching for frequently accessed data
Hierarchy Overview
ClickUp uses a hierarchical structure:
Available Tools
Workspace & Space Management
list_workspaces
List all accessible workspaces (teams).
Example:
list_spaces
List spaces in a workspace.
Parameters:
workspace_id
(string, required): Workspace IDarchived
(bool, optional): Include archived (default: false)
Example:
get_space
Get space details.
Parameters:
space_id
(string, required): Space ID
Example:
Folder & List Management
list_folders
List folders in a space.
Parameters:
space_id
(string, required): Space IDarchived
(bool, optional): Include archived (default: false)
Example:
list_lists
List lists in a folder or space.
Parameters:
folder_id
(string, optional): Folder IDspace_id
(string, optional): Space ID (for folderless lists)archived
(bool, optional): Include archived (default: false)
Example:
Task Management
list_tasks
List tasks with filters.
Parameters:
list_id
(string, required): List IDarchived
(bool, optional): Include archived (default: false)page
(int, optional): Page number (default: 0)order_by
(string, optional): Order by (created, updated, due_date)reverse
(bool, optional): Reverse order (default: true)subtasks
(bool, optional): Include subtasks (default: true)statuses
(list, optional): Filter by status namesinclude_closed
(bool, optional): Include closed tasks (default: false)assignees
(list, optional): Filter by assignee user IDstags
(list, optional): Filter by tag namesdue_date_gt
(int, optional): Due date greater than (Unix ms)due_date_lt
(int, optional): Due date less than (Unix ms)
Example:
get_task
Get task details with custom fields.
Parameters:
task_id
(string, required): Task ID
Example:
create_task
Create a new task.
Parameters:
list_id
(string, required): List IDname
(string, required): Task namedescription
(string, optional): Task descriptionassignees
(list, optional): Assignee user IDstags
(list, optional): Tag namesstatus
(string, optional): Status namepriority
(int, optional): Priority (1=urgent, 2=high, 3=normal, 4=low)due_date
(int, optional): Due date (Unix timestamp ms)due_date_time
(bool, optional): Include time (default: false)time_estimate
(int, optional): Time estimate in millisecondsstart_date
(int, optional): Start date (Unix timestamp ms)start_date_time
(bool, optional): Include time (default: false)notify_all
(bool, optional): Notify assignees (default: true)parent
(string, optional): Parent task ID (for subtasks)custom_fields
(list, optional): Custom field objects
Priority Levels:
1: Urgent (red flag)
2: High (yellow flag)
3: Normal (blue flag, default)
4: Low (gray flag)
Example:
update_task
Update task details.
Parameters:
task_id
(string, required): Task IDname
(string, optional): Updated namedescription
(string, optional): Updated descriptionstatus
(string, optional): Updated statuspriority
(int, optional): Updated priority (1-4)due_date
(int, optional): Updated due date (Unix ms)time_estimate
(int, optional): Updated time estimate (ms)assignees
(dict, optional): Assignees {"add": [ids], "rem": [ids]}
Example:
delete_task
Delete a task.
Parameters:
task_id
(string, required): Task ID
Example:
Comments
add_task_comment
Add comment to a task.
Parameters:
task_id
(string, required): Task IDcomment_text
(string, required): Comment textassignee
(int, optional): Assign comment to user IDnotify_all
(bool, optional): Notify all assignees (default: true)
Example:
list_task_comments
Get task comments.
Parameters:
task_id
(string, required): Task ID
Example:
Time Tracking
create_time_entry
Track time on a task.
Parameters:
task_id
(string, required): Task IDduration
(int, required): Duration in millisecondsstart
(int, optional): Start time (Unix ms, defaults to now)description
(string, optional): Time entry description
Example:
list_time_entries
Get time tracking entries.
Parameters:
workspace_id
(string, required): Workspace IDstart_date
(int, optional): Filter by start date (Unix ms)end_date
(int, optional): Filter by end date (Unix ms)assignee
(int, optional): Filter by assignee user ID
Example:
Goals
list_goals
List goals in a workspace.
Parameters:
workspace_id
(string, required): Workspace ID
Example:
get_goal
Get goal details and progress.
Parameters:
goal_id
(string, required): Goal ID
Example:
Custom Fields
list_custom_fields
Get custom fields for a list.
Parameters:
list_id
(string, required): List ID
Example:
Custom Field Types:
text
: Text inputnumber
: Numeric inputdrop_down
: Dropdown selectiondate
: Date pickercheckbox
: Boolean checkboxurl
: URL inputemail
: Email inputphone
: Phone numbercurrency
: Currency value
Search
search_tasks
Search tasks across workspace.
Parameters:
workspace_id
(string, required): Workspace IDquery
(string, required): Search query textstart_date
(int, optional): Filter by start date (Unix ms)end_date
(int, optional): Filter by end date (Unix ms)assignees
(list, optional): Filter by assignee user IDsstatuses
(list, optional): Filter by status namestags
(list, optional): Filter by tag names
Example:
Common Workflows
Project Setup
Sprint Planning
Time Tracking Report
Goal Tracking
Best Practices
Use hierarchy effectively: Organize with Spaces → Folders → Lists
Custom statuses: Set up workflows per list
Custom fields: Add metadata for filtering and reporting
Time tracking: Log time regularly for accurate estimates
Tags: Use tags for cross-list categorization
Goals: Set measurable goals with key results
Priorities: Use priority levels consistently
Assignees: Assign tasks for accountability
Comments: Communicate within tasks
Search: Use search for cross-workspace queries
Rate Limit Handling
Error Handling
Common errors:
401 Unauthorized: Invalid API token
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
429 Too Many Requests: Rate limit exceeded (100 req/min)
500 Internal Server Error: ClickUp service issue
API Documentation
Support
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables comprehensive project management through ClickUp's API, supporting task creation and updates, time tracking, goal management, and team collaboration within ClickUp's hierarchical workspace structure.