ClickUp MCP for AI Assistants

Fork of @hauptsache.net/clickup-mcp with custom task ID support and additional features.

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.

Differences From the Upstream Project

This fork is published as @sebastienheyd/clickup-mcp and follows its own version numbers. Upstream history is merged (last sync: upstream 1.9.0, September 2026), so the two projects share their core; the fork keeps its own additions on top.

See CHANGELOG.md for this fork's history and the upstream changelog for theirs.

This MCP vs Official ClickUp MCP

See also: Official ClickUp MCP Documentation

Choose this MCP when:

• You need rich task context with inline images for AI coding tools
• You want to write screenshots into tickets by local file path (running locally, it reads the file itself instead of taking base64)
• You need API key authentication for automation or CI/CD pipelines
• You want the read-minimal mode optimized for development workflows

Choose Official MCP when:

• You need OAuth authentication for enterprise security compliance
• You need Chat integration or Connected Search features
• You want official support and no local installation

What You Can Do

Turn natural language into powerful ClickUp actions:

Agentic Coding & Development:

• "Look at CU-abc123, can you find the relevant code?"
• "Can you build the dashboard like described in https://app.clickup.com/t/12a23b45c?"
• "Check task CU-xyz789 and fix the bugs mentioned in the comments"
• "Implement the API endpoints described in the integration task"

Time Tracking & Productivity:

• "Book 2 hours for the client meeting on the XYZ project"
• "How much time did I spend on development tasks this week?"
• "Log 30 minutes for code review on the authentication feature"

Smart Search & Discovery:

• "What task did I mention the CSV import in?"
• "Find all tasks related to the payment gateway integration"
• "Show me tasks where users reported login issues"

Daily Workflow Management:

• "What do I need to do today?"
• "Create a task for fixing the dashboard bug in the frontend list"
• "Update the API documentation task to 'in review' status"
• "What tasks are blocking the mobile app release?"

Rich Context & Collaboration:

• "Show me all comments on the user authentication task"
• "What's the latest update on the database migration?"
• "Add a comment to the design task about the new wireframes"

Document Management:

• "Find documents about job posting in my space"
• "Search for API documentation across all spaces"
• "Read the API documentation in the development space"
• "Create a new requirements document for the mobile app project"
• "Update the meeting notes with today's decisions"
• "What documents are in the product strategy space?"

Key Features

🔍 Intelligent Search

• Fuzzy matching across task names, descriptions, and comments
• Multi-language search support for international teams
• Filter by assignees, projects, status, and metadata

💬 Complete Context

• Full comment histories and team discussions
• Task descriptions with embedded images
• List descriptions and project guidelines
• Document content with page navigation
• Access to complete task history and decisions

⏱️ Time Tracking

• Log time entries with descriptions
• View historical time logs and entries
• Query time entries by task or date range

📋 Task & Document Management

• Create and update tasks with markdown descriptions
• Create, read, and update documents and pages
• Add comments and collaborate with team members
• Manage priorities, due dates, assignees, and tags
• Handle time estimates, sprint points and custom field values

🔒 Safety Features

• Append-First Descriptions: append_description adds a dated block under the existing description and is the default for notes. description rewrites the whole description on purpose - the previous content is echoed back so a wrong replacement can be undone
• Normal Field Updates: Status, priority, assignees, tags, and dates can be updated normally (easily revertible through ClickUp's history)

Installation

Prerequisites

For all installation methods, you'll need:

• Your CLICKUP_API_KEY (Profile Icon > Settings > Apps > API Token ~ usually starts with pk_)
• Your CLICKUP_TEAM_ID (The 7–10 digit number in the URL when you are in the settings)

Option 1: MCPB Bundle (Recommended for Claude Desktop)

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.

Option 2: NPX Installation

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": [
        "@sebastienheyd/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 Desktop: Settings > Developer > Edit Config
• Windsurf: Add to your MCP configuration file
• Cursor: Configure through the MCP settings panel

Option 3: Coding Tools Integration

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 @sebastienheyd/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", "@sebastienheyd/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.

MCP Modes & Available Tools

The ClickUp MCP supports three operational modes to balance functionality, security, and performance:

• 🚀 `read-minimal`: Perfect for AI coding assistants and context gathering
• 📖 `read`: Full read-only access for project exploration and workflow understanding
• ✏️ `write` (Default): Complete functionality for task management and productivity workflows

Setting the Mode

Add the mode to your MCP configuration:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "@sebastienheyd/clickup-mcp@latest"],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id",
        "CLICKUP_MCP_MODE": "read"
      }
    }
  }
}

Configuration

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.
• MAX_UPLOAD_SIZE_MB: (Optional) The maximum size of a single image uploaded when writing comments or descriptions. Defaults to 10.
• CLICKUP_COMMENT_EDIT_WINDOW_HOURS: (Optional) How long after creation editComment may still rewrite a comment. Defaults to 24. Set to 0 to disable comment editing entirely.
• 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.

Language-Aware Search Guidance

The searchTask tool's description will dynamically adjust based on the detected primary language:

• If 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.
• If no primary language is detected, a more general recommendation for multilingual workspaces will be provided.

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.

Markdown Formatting Support

Task descriptions and list documentation support full markdown formatting:

Examples

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 or Replace Descriptions: By default (append_description), content is appended under the existing description:

[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 keeps existing content and a clear audit trail. To correct or restructure a description, description rewrites it entirely; the tool answers with the previous description so nothing is silently lost. The same two parameters exist on updateListInfo.

Writing Images Into Tickets

addComment, createTask and updateTask accept images as ordinary markdown. Because this server runs locally, it reads the file itself - so a local path is enough:

Ist umgesetzt. So sieht es aus:

**1. Login öffnen** – der Kunde gibt nur seine E-Mail-Adresse ein.

![Die Login-Maske fragt nur nach der E-Mail](/Users/me/shots/login.png)

Accepted sources: local file paths, data: URIs, http(s) URLs (downloaded, then re-uploaded), and existing ClickUp attachment URLs (embedded without re-uploading).

Notes:

• Prefer paths over base64. A path costs a few tokens; the same screenshot as a

data: URI costs roughly 4/3 of its file size in the request.

• The caption becomes the attachment filename, and that filename is what ClickUp

displays beneath the image - so write a caption that reads well.

• An image inside a numbered list breaks ClickUp's numbering. Write walkthrough

steps as bold lines with the image between them, as above.

• Only real PNG/JPEG/GIF/WebP files are uploaded - the content is checked, not the

extension. A file that fails aborts the write: addComment and updateTask report every broken reference and change nothing, so the markdown can be fixed and the call retried without creating duplicates. createTask validates its images before creating the task; only an upload failing afterwards is reported as a warning, since the task already exists at that point.

• Attachments always belong to a task, so document pages cannot embed uploads this way.
• `editComment` can only keep the images already in the comment. Pass the markdown

returned by getTaskById back and they stay; ClickUp refuses to add any other image to an existing comment, so a new image reference is rejected before anything is uploaded. Share a new image in a new comment with addComment instead.

Performance & Limitations

Optimized for AI Workflows:

• Smart Image Processing: Intelligent size budgeting prioritizes the most recent images while respecting both count (MAX_IMAGES, default: 4) and total response size limits (MAX_RESPONSE_SIZE_MB, default: 1MB)
• Search Scope: Searches within the most recent 1000-3000 tasks to prevent running into rate limits (exact number varies by endpoint)
• Search Results: Returns up to 50 most relevant matches to prevent flooding the agent with too many results

Current Scope:

• Focused on task-level operations rather than bulk workspace management
• Optimized for conversational AI workflows rather than data migration
• Designed for productivity enhancement, not administrative operations

These limitations ensure reliable performance while covering the most common use cases for both development context and productivity management.

License

MIT