clickup-mcp-server
by: TaazKareem
ClickUp MCP Server - Integrate ClickUp task management with AI through Model Context Protocol
📌Overview
Purpose: To provide a Model Context Protocol (MCP) server for seamless integration between ClickUp tasks and AI applications, enabling efficient task management through a standardized protocol.
Overview: The ClickUp MCP server facilitates interaction between AI agents and ClickUp, allowing users to manage tasks, folders, and lists through natural language requests. It supports various installation methods and is designed for both hosted and local environments.
Key Features:
-
Comprehensive Task Management: Create, update, delete, and organize tasks easily. It supports single and bulk operations, due date assignments using natural language, and manages subtasks, comments, and attachments.
-
Flexible Workspace Organization: Navigate and manage ClickUp's workspace structure, including spaces, folders, and lists. Users can view the hierarchy and efficiently manage their projects.
-
Error Handling & Logging: The server includes robust error handling for common issues and allows users to control logging verbosity for better tracking and debugging.
ClickUp MCP Server
A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, lists, and folders through a standardized protocol.
🚧 Status Update: Rolling out v0.6.9 will add Global Task Lookup with smart disambiguation, Start Date Support for tasks with natural language expressions, Complete Tag Support including natural language tag color commands, Subtasks Support, Custom ID Support, and Logging Fixes.
Setup
- Get your credentials:
- ClickUp API key from ClickUp Settings: https://app.clickup.com/settings/apps
- Team ID from your ClickUp workspace URL
- Choose either hosted installation (sends webhooks) or NPX installation (downloads to local path and installs dependencies).
- Use natural language to manage your workspace!
Smithery Installation (Quick Start)
The server is hosted on Smithery: https://smithery.ai/server/@taazkareem/clickup-mcp-server. There, you can preview the available tools or copy the commands to run on your specific client app.
NPX Installation
Add this entry to your client's MCP settings JSON file:
{
"mcpServers": {
"ClickUp": {
"command": "npx",
"args": [
"-y",
"@taazkareem/clickup-mcp-server@latest"
],
"env": {
"CLICKUP_API_KEY": "your-api-key",
"CLICKUP_TEAM_ID": "your-team-id"
}
}
}
}
Or use this npx command:
npx -y @taazkareem/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id
Features
| 📝 Task Management | 🏷️ Tag Management |
|---|---|
| • Create, update, and delete tasks | |
| • Move and duplicate tasks anywhere | |
| • Support for single and bulk operations | |
| • Set start/due dates with natural language | |
| • Create and manage subtasks | |
| • Add comments and attachments | • Create, update, and delete space tags |
| • Add and remove tags from tasks | |
| • Use natural language color commands | |
| • Automatic contrasting foreground colors | |
| • View all space tags | |
| • Tag-based task organization across workspace |
| ⏱️ Time Tracking | 🌳 Workspace Organization |
|---|---|
| • View time entries for tasks | |
| • Start/stop time tracking on tasks | |
| • Add manual time entries | |
| • Delete time entries | |
| • View currently running timer | |
| • Track billable and non-billable time | • Navigate spaces, folders, and lists |
| • Create and manage folders | |
| • Organize lists within spaces | |
| • Create lists in folders | |
| • View workspace hierarchy | |
| • Efficient path navigation |
| ⚡ Integration Features | |
|---|---|
| • Global name or ID-based lookups | |
| • Case-insensitive matching | |
| • Markdown formatting support | |
| • Built-in rate limiting | |
| • Error handling and validation | |
| • Comprehensive API coverage |
Available Tools
| Tool | Description | Required Parameters |
|---|---|---|
| get_workspace_hierarchy | Get workspace structure | None |
| create_task | Create a task | name, (listId/listName) |
| create_bulk_tasks | Create multiple tasks | tasks[] |
| update_task | Modify task | taskId/taskName |
| update_bulk_tasks | Update multiple tasks | tasks[] with IDs or names |
| get_tasks | Get tasks from list | listId/listName |
| get_task | Get single task details | taskId/taskName (with smart disambiguation) |
| get_workspace_tasks | Get tasks with filtering | At least one filter (tags, list_ids, space_ids, etc.) |
| get_task_comments | Get comments on a task | taskId/taskName |
| create_task_comment | Add a comment to a task | commentText, (taskId/(taskName+listName)) |
| attach_task_file | Attach file to a task | taskId/taskName, (file_data or file_url) |
| delete_task | Remove task | taskId/taskName |
| delete_bulk_tasks | Remove multiple tasks | tasks[] with IDs or names |
| move_task | Move task | taskId/taskName, listId/listName |
| move_bulk_tasks | Move multiple tasks | tasks[] with IDs or names, target list |
| duplicate_task | Copy task | taskId/taskName, listId/listName |
| create_list | Create list in space | name, spaceId/spaceName |
| create_folder | Create folder | name, spaceId/spaceName |
| create_list_in_folder | Create list in folder | name, folderId/folderName |
| get_folder | Get folder details | folderId/folderName |
| update_folder | Update folder properties | folderId/folderName |
| delete_folder | Delete folder | folderId/folderName |
| get_list | Get list details | listId/listName |
| update_list | Update list properties | listId/listName |
| delete_list | Delete list | listId/listName |
| get_space_tags | Get space tags | spaceId/spaceName |
| create_space_tag | Create tag | tagName, spaceId/spaceName |
| update_space_tag | Update tag | tagName, spaceId/spaceName |
| delete_space_tag | Delete tag | tagName, spaceId/spaceName |
| add_tag_to_task | Add tag to task | tagName, taskId/(taskName+listName) |
| remove_tag_from_task | Remove tag from task | tagName, taskId/(taskName+listName) |
| get_task_time_entries | Get time entries for a task | taskId/taskName |
| start_time_tracking | Start time tracking on a task | taskId/taskName |
| stop_time_tracking | Stop current time tracking | None |
| add_time_entry | Add manual time entry to a task | taskId/taskName, start, duration |
| delete_time_entry | Delete a time entry | timeEntryId |
| get_current_time_entry | Get currently running timer | None |
See full documentation for optional parameters and advanced usage.
Prompts
Not yet implemented and not supported by all client apps. Request a feature for a Prompt implementation that would be most beneficial for your workflow. Examples:
| Prompt | Purpose | Features |
|---|---|---|
| summarize_tasks | Task overview | Status summary, priorities, relationships |
| analyze_priorities | Priority optimization | Distribution analysis, sequencing |
| generate_description | Task description creation | Objectives, criteria, dependencies |
Error Handling
The server provides clear error messages for:
- Missing required parameters
- Invalid IDs or names
- Items not found
- Permission issues
- API errors
- Rate limiting
The LOG_LEVEL environment variable controls the verbosity of server logs. Valid values are trace, debug, info, warn, and error (default).
This can also be specified on the command line as, e.g., --env LOG_LEVEL=info.
Support the Developer
When using this server, you may occasionally see a small sponsor message with a link to this repository included in tool responses. If you find this project useful, please consider supporting:
Acknowledgements
Special thanks to ClickUp for their excellent API and services that make this integration possible.
Contributing
Contributions are welcome! Please read the Contributing Guide for details.
License
This project is licensed under the MIT License.
Disclaimer
This software uses third-party APIs and may reference trademarks or brands owned by third parties. The use of such APIs or references does not imply any affiliation with or endorsement by the respective companies. All trademarks and brand names are the property of their respective owners. This project is independent and not officially associated with or sponsored by any third-party company mentioned.