ClickUp

clickup-mcp-server: AI-Powered ClickUp Integration

What is clickup-mcp-server?

clickup-mcp-server is a Model Context Protocol (MCP) server designed to integrate ClickUp project management with AI applications. It enables AI agents to interact with ClickUp tasks, spaces, lists, and folders through a standardized protocol, facilitating natural language-based workspace management.

How to use clickup-mcp-server?

To use clickup-mcp-server, you need your ClickUp API key and Team ID. You can choose between a hosted installation (via Smithery) or an NPX installation. For NPX installation, you add the server to your client's MCP settings JSON file or run a direct npx command. The server supports both modern HTTP Streamable transport and legacy SSE transport. You can also filter available tools using ENABLED_TOOLS or DISABLED_TOOLS environment variables.

Key Features of clickup-mcp-server

Task Management: Create, update, delete, move, and duplicate tasks; support for bulk operations; set dates with natural language; manage subtasks, comments, and attachments.

Tag Management: Create, update, and delete space tags; add/remove tags from tasks; natural language color commands; automatic contrasting foreground colors; tag-based task organization.

Time Tracking: View, start/stop, add, and delete time entries; track billable/non-billable time.

Workspace Organization: Navigate spaces, folders, and lists; create and manage folders/lists; view workspace hierarchy; efficient path navigation.

Document Management: Document listing, page listing, page details, creation, and updates (append & prepend).

Member Management: Find workspace members; resolve assignees for tasks; view member details and permissions; assign tasks to users.

Integration Features: Global name/ID-based lookups; case-insensitive matching; Markdown formatting; built-in rate limiting; error handling; comprehensive API coverage.

Architecture & Performance: 70% codebase reduction; unified architecture; zero code duplication; HTTP Streamable and legacy SSE transport support.

Use Cases of clickup-mcp-server

• AI-powered Project Management: Allow AI agents to create, update, and manage tasks in ClickUp based on natural language commands.
• Automated Workflow: Automate task creation, assignment, and updates within ClickUp through integration with AI systems.
• Enhanced Productivity: Streamline project management by enabling AI to interact directly with ClickUp, reducing manual effort.
• Custom Integrations: Build custom applications and integrations that leverage ClickUp's functionalities through the MCP server.

FAQ from clickup-mcp-server

Q: How do I control which tools are available? A: You can use the ENABLED_TOOLS environment variable to specify exactly which tools should be available, or DISABLED_TOOLS to disable specific ones. ENABLED_TOOLS takes precedence.

Q: Does it support both modern and legacy transport protocols? A: Yes, the server supports both modern HTTP Streamable transport (MCP Inspector compatible) and legacy SSE (Server-Sent Events) transport for backwards compatibility.

Q: How can I integrate with n8n? A: Start the clickup-mcp-server with SSE enabled, then in n8n, add a new "MCP AI Tool" node and configure it with SSE transport and the server URL.

Q: What kind of error handling does the server provide? A: The server provides clear error messages for missing parameters, invalid IDs, items not found, permission issues, API errors, and rate limiting. You can control log verbosity with the LOG_LEVEL environment variable.

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: v0.8.3 is released with major enhancements! Enhanced workspace tasks filtering with Views API support for multi-list tasks (Issue #43), added ENABLED_TOOLS configuration option (Issue #50), and fixed automatic priority assignment in task creation. See Release Notes for full details.

Setup

1. Get your credentials:
   • ClickUp API key from ClickUp Settings
   • Team ID from your ClickUp workspace URL
2. Choose either hosted installation (sends webhooks) or NPX installation (downloads to local path and installs dependencies)
3. Use natural language to manage your workspace!

Smithery Installation (Quick Start)

The server is hosted on Smithery. 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",
        "DOCUMENT_SUPPORT": "true"
      }
    }
  }
}

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

Obs: if you don't pass "DOCUMENT_SUPPORT": "true", the default is false and document support will not be active.

Tool Filtering

You can control which tools are available using two complementary environment variables:

ENABLED_TOOLS (Recommended)

Use ENABLED_TOOLS to specify exactly which tools should be available:

# Environment variable
export ENABLED_TOOLS="create_task,get_task,update_task,get_workspace_hierarchy"

# Command line argument
--env ENABLED_TOOLS=create_task,get_task,update_task,get_workspace_hierarchy

DISABLED_TOOLS (Legacy)

Use DISABLED_TOOLS to disable specific tools while keeping all others enabled:

# Environment variable
export DISABLED_TOOLS="delete_task,delete_bulk_tasks"

# Command line argument
--env DISABLED_TOOLS=delete_task,delete_bulk_tasks

Precedence Rules

• If ENABLED_TOOLS is specified, only those tools will be available (takes precedence over DISABLED_TOOLS)
• If only DISABLED_TOOLS is specified, all tools except those listed will be available
• If neither is specified, all tools are available (default behavior)

Example:

# Only enable task creation and reading tools
npx -y @taazkareem/clickup-mcp-server@latest \
  --env CLICKUP_API_KEY=your-api-key \
  --env CLICKUP_TEAM_ID=your-team-id \
  --env ENABLED_TOOLS=create_task,get_task,get_workspace_hierarchy

Please filter tools you don't need if you are having issues with the number of tools or any context limitations.

Running with HTTP Transport Support

The server supports both modern HTTP Streamable transport (MCP Inspector compatible) and legacy SSE (Server-Sent Events) transport for backwards compatibility.

{
  "mcpServers": {
    "ClickUp": {
      "command": "npx",
      "args": [
        "-y",
        "@taazkareem/clickup-mcp-server@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your-api-key",
        "CLICKUP_TEAM_ID": "your-team-id",
        "ENABLE_SSE": "true",
        "PORT": "3231"
      }
    }
  }
}

Endpoints:

• Primary: http://127.0.0.1:3231/mcp (Streamable HTTP)
• Legacy: http://127.0.0.1:3231/sse (SSE for backwards compatibility)

Command Line Usage

npx -y @taazkareem/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id --env ENABLE_SSE=true --env PORT=3231

Available configuration options:

Option	Description	Default
ENABLED_TOOLS	Comma-separated list of tools to enable (takes precedence)	All tools
DISABLED_TOOLS	Comma-separated list of tools to disable	None
ENABLE_SSE	Enable the HTTP/SSE transport	false
PORT	Port for the HTTP server	3231
ENABLE_STDIO	Enable the STDIO transport	true

n8n Integration

To integrate with n8n:

1. Start the clickup-mcp-server with SSE enabled
2. In n8n, add a new "MCP AI Tool" node
3. Configure the node with:
   • Transport: SSE
   • Server URL: http://localhost:3231 (or your server address)
   • Tools: Select the ClickUp tools you want to use

Example Client

An example SSE client is provided in the examples directory. To run it:

# Start the server with SSE enabled
ENABLE_SSE=true PORT=3231 npx -y @taazkareem/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id

# In another terminal, run the example client
cd examples
npm install
npm run sse-client

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
📄 Document Management	👥 Member Management
• Document Listing through all workspace• Document Page listing• Document Page Details• Document Creation• Document page update (append & prepend)	• Find workspace members by name or email• Resolve assignees for tasks• View member details and permissions• Assign tasks to users during creation and updates• Support for user IDs, emails, or usernames• Team-wide user management
⚡ Integration Features	🏗️ Architecture & Performance
• Global name or ID-based lookups• Case-insensitive matching• Markdown formatting support• Built-in rate limiting• Error handling and validation• Comprehensive API coverage	• 70% codebase reduction for improved performance• Unified architecture across all transport types• Zero code duplication• HTTP Streamable transport (MCP Inspector compatible)• Legacy SSE support for backwards compatibility

Available Tools (36 Total)

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
get_workspace_members	Get all workspace members	None
find_member_by_name	Find member by name or email	nameOrEmail
resolve_assignees	Resolve member names to IDs	assignees[]
create_document	Create a document	workspaceId, name, parentId/parentType, visibility, create_pages
get_document	Get a document	workspaceId/documentId
list_documents	List documents	workspaceId, documentId/creator/deleted/archived/parent_id/parent_type/limit/next_cursor
list_document_pages	List document pages	documentId/documentName
get_document_pages	Get document pages	documentId/documentName, pageIds
create_document_pages	Create a document page	workspaceId/documentId, parent_page_id/name/sub_title,content/content_format
update_document_page	Update a document page	workspaceId/documentId, name/sub_title,content/content_edit_mode/content_format

See full documentation for optional parameters and advanced usage.

Member Management Tools

When creating or updating tasks, you can assign users using the assignees parameter. The parameter accepts an array of user IDs, emails, or usernames:

Creating tasks with assignees:

{
  "name": "New Task",
  "description": "This is a new task.",
  "assignees": ["jdoe@example.com", "Jane Smith"]  // Emails, usernames, or user IDs
}

Updating task assignees:

{
  "taskId": "abc123",
  "assignees": ["newuser@example.com"]  // Replace existing assignees
}

The member management tools help resolve user references when needed.

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 (without it being too specific). 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 can be specified to control the verbosity of server logs. Valid values are trace, debug, info, warn, and error (default). This can be 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. I hope you can support the project! 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 our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This software makes use of 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 an independent work and is not officially associated with or sponsored by any third-party company mentioned.