ClickUp
STDIO连接ClickUp工作空间的MCP服务器
连接ClickUp工作空间的MCP服务器
Model Context Protocol (MCP) server enabling AI assistants to interact with ClickUp workspaces. Get complete task context with comments and images, search across projects, create and update tasks, collaborate through comments, and track time - all through natural language.
Turn natural language into powerful ClickUp actions:
Agentic Coding & Development:
Time Tracking & Productivity:
Smart Search & Discovery:
Daily Workflow Management:
Rich Context & Collaboration:
Document Management:
For all installation methods, you'll need:
CLICKUP_API_KEY (Profile Icon > Settings > Apps > API Token ~ usually starts with pk_)CLICKUP_TEAM_ID (The 7–10 digit number in the URL when you are in the settings)Download the pre-built bundle from our releases page. This method requires no Node.js installation.
You'll get a configuration screen where you are prompted to enter your API key and team ID.
This method automatically updates to the latest version and is preferred for users who want the newest features.
For Claude Desktop, Windsurf, Cursor and others:
Add the following to your MCP configuration file:
{ "mcpServers": { "clickup": { "command": "npx", "args": [ "@hauptsache.net/clickup-mcp@latest" ], "env": { "CLICKUP_API_KEY": "your_api_key", "CLICKUP_TEAM_ID": "your_team_id" } } } }
Replace your_api_key and your_team_id with your actual ClickUp credentials.
Where to add this configuration:
Claude Code (CLI):
claude mcp add --scope user clickup \ --env CLICKUP_API_KEY=YOUR_KEY \ --env CLICKUP_TEAM_ID=YOUR_ID \ --env CLICKUP_MCP_MODE=read-minimal \ --env MAX_IMAGES=16 \ --env MAX_RESPONSE_SIZE_MB=4 \ -- npx -y @hauptsache.net/clickup-mcp
Claude Code can handle a lot of images, thus the recommended increased limits.
Note the
CLICKUP_MCP_MODE=read-minimal. This is my usage recommendation, but feel free to use one of the other modes.
OpenAI Codex:
Add these lines to your ~/.codex/config.toml file:
[mcp_servers.clickup] command = "npx" args = ["-y", "@hauptsache.net/clickup-mcp@latest"] env = { "CLICKUP_API_KEY" = "YOUR_KEY", "CLICKUP_TEAM_ID" = "YOUR_ID", "CLICKUP_MCP_MODE" = "read-minimal" }
Codex seems to not be able to handle images from MCP's. See this issue for more details.
Note the
CLICKUP_MCP_MODE=read-minimal. This is my usage recommendation, but feel free to use one of the other modes.
The ClickUp MCP supports three operational modes to balance functionality, security, and performance:
read-minimal: Perfect for AI coding assistants and context gatheringread: Full read-only access for project exploration and workflow understandingwrite (Default): Complete functionality for task management and productivity workflows| Tool | read-minimal | read | write | Description |
|---|---|---|---|---|
getTaskById | ✅ | ✅ | ✅ | Get complete task details including comments, images, and metadata |
addComment | ❌ | ❌ | ✅ | Add comments to tasks for collaboration |
updateTask | ❌ | ❌ | ✅ | Update tasks (status, priority, assignees, etc.) with SAFE APPEND-ONLY descriptions |
createTask | ❌ | ❌ | ✅ | Create new tasks with full markdown support |
searchTasks | ✅ | ✅ | ✅ | Find tasks by content, keywords, assignees, or project context |
searchSpaces | ❌ | ✅ | ✅ | Browse workspace structure, project organization, and documents |
getListInfo | ❌ | ✅ | ✅ | Get list details and available statuses for task creation |
updateListInfo | ❌ | ❌ | ✅ | SAFE APPEND-ONLY updates to list descriptions (preserves existing content) |
getTimeEntries | ❌ | ✅ | ✅ | View time entries and analyze time spent across projects |
createTimeEntry | ❌ | ❌ | ✅ | Log time entries for task tracking |
readDocument | ❌ | ✅ | ✅ | Get document details, page structure, and content with navigation |
searchDocuments | ❌ | ✅ | ✅ | Search documents by name and space with fuzzy matching and space filtering |
updateDocumentPage | ❌ | ❌ | ✅ | Update existing page content or name with replace/append modes |
createDocumentOrPage | ❌ | ❌ | ✅ | Create new documents with first page, or add pages/sub-pages to existing documents |
Add the mode to your MCP configuration:
{ "mcpServers": { "clickup": { "command": "npx", "args": ["-y", "@hauptsache.net/clickup-mcp@latest"], "env": { "CLICKUP_API_KEY": "your_api_key", "CLICKUP_TEAM_ID": "your_team_id", "CLICKUP_MCP_MODE": "read" } } } }
This MCP server can be configured using environment variables:
CLICKUP_API_KEY: (Required) Your ClickUp API key.CLICKUP_TEAM_ID: (Required) Your ClickUp Team ID (formerly Workspace ID).CLICKUP_MCP_MODE: (Optional) Controls which tools are available. Options: read-minimal, read, write (default).MAX_IMAGES: (Optional) The maximum number of images to return for a task in getTaskById. Defaults to 4.MAX_RESPONSE_SIZE_MB: (Optional) The maximum response size in megabytes for getTaskById. Uses intelligent size budgeting to fit the most important images within the limit. Defaults to 1.CLICKUP_PRIMARY_LANGUAGE: (Optional) A hint for the primary language used in your ClickUp tasks (e.g., "de" for German, "en" for English). This helps the searchTask tool provide more tailored guidance in its description for multilingual searches.LANG: (Optional) If CLICKUP_PRIMARY_LANGUAGE is not set, the MCP will check this standard environment variable (e.g., "en_US.UTF-8", "de_DE") as a fallback to infer the primary language.The searchTask tool's description will dynamically adjust based on the detected primary language:
CLICKUP_PRIMARY_LANGUAGE or LANG suggests a known primary language (e.g., German), the tool's description will specifically recommend providing search terms in both English and that detected language (e.g., German) for optimal results.This feature aims to improve search effectiveness when the language of user queries (often English) differs from the language of the tasks in ClickUp, without making the MCP itself perform translations. The responsibility for providing bilingual search terms still lies with the agent calling the MCP, but the MCP offers more specific advice if it has a language hint.
Task descriptions and list documentation support full markdown formatting:
Task Creation with Markdown:
Create a task called "API Integration" with description:
# API Integration Requirements
## Authentication
- Implement OAuth 2.0 flow
- Add JWT token validation
- **Priority**: High security standards
## Endpoints
1. `/api/users` - User management
2. `/api/data` - Data retrieval
3. `/api/webhook` - Event notifications
## Testing
- [ ] Unit tests for auth flow
- [ ] Integration tests
- [ ] Load testing with 1000+ concurrent users
> **Note**: This replaces the legacy REST implementation
See related task: https://app.clickup.com/t/abc123
Append-Only Updates (Safe): When updating task descriptions, content is safely appended:
[Existing task description content] --- **Edit (2024-01-15):** Added new acceptance criteria based on client feedback: - Must support mobile responsive design - Performance requirement: < 2s load time
This ensures no existing content is ever lost while maintaining a clear audit trail.
Optimized for AI Workflows:
MAX_IMAGES, default: 4) and total response size limits (MAX_RESPONSE_SIZE_MB, default: 1MB)Current Scope:
These limitations ensure reliable performance while covering the most common use cases for both development context and productivity management.
MIT