playbooks

home / mcp / clickup mcp server

ClickUp MCP Server

Provides an MCP server to interact with ClickUp workspaces via natural language for task management, search, and collaboration.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "hauptsachenet-clickup-mcp": {
      "command": "npx",
      "args": [
        "@hauptsache.net/clickup-mcp@latest"
      ],
      "env": {
        "MAX_IMAGES": "4",
        "CLICKUP_API_KEY": "YOUR_API_KEY",
        "CLICKUP_TEAM_ID": "YOUR_TEAM_ID",
        "CLICKUP_MCP_MODE": "read-minimal",
        "MAX_RESPONSE_SIZE_MB": "1"
      }
    }
  }
}

You can run a ClickUp MCP server locally to let AI assistants interact with your ClickUp workspaces using natural language. It provides complete task context, flexible search, task and document management, time tracking, and rich collaboration features, all accessible through simple prompts in your preferred AI environment.

How to use

Use an MCP client to talk to the ClickUp MCP server. You can ask it to retrieve full task details, search across projects, create or update tasks, add comments, and log time with natural language. Rely on intelligent search to surface relevant tasks, and leverage inline images and markdown-enabled task descriptions for rich context. You can also ask the server to fetch or update documents and pages, read task histories, and track time entries across tasks and spaces.

How to install

Prerequisites: ensure you have a current Node.js runtime installed (Node.js 14+ is recommended). You also need your ClickUp API key and your ClickUp Team ID.

Choose an installation approach that fits your workflow.

Option 1: MCP Bundle for Claude Desktop (recommended for non-developer setups) is available as a pre-built bundle. Install the bundle from the releases page, then follow the on-screen prompts to enter your API key and team ID.

Option 2: NPX Installation (recommended for developers or those who want the latest features). Configure your MCP client to load the server via NPX using the following configuration snippet.

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": [
        "@hauptsache.net/clickup-mcp@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id"
      }
    }
  }
}

Option 3: Coding Tools Integration commands

If you integrate with coding tools, you can run the MCP server via a CLI entry like this.

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

MCP modes and available tools

The server supports three modes to balance functionality and security: read-minimal, read, and write. The read-minimal mode is ideal for coding assistants and context gathering, read provides full read-only access for exploration, and write enables complete task management capabilities.

Configuration & notes

Configure the MCP server using environment variables to control authentication, mode, and performance. Key variables include the API key, the team ID, and the desired mode. The system supports limiting the number of images returned and the maximum response size to ensure fast, focused results.

The following snippet shows how to set environment variables in the NPX configuration example.

{
  "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-minimal"
      }
    }
  }
}

Available tools

getTaskById

Fetch complete task details by ID, including comments, images, and metadata.

addComment

Add a comment to a task to support collaboration.

updateTask

Update task fields such as status, priority, assignees, and descriptions with safe append behavior.

createTask

Create a new task with markdown-enabled descriptions.

searchTasks

Find tasks by content, keywords, assignees, or project context using fuzzy matching.

searchSpaces

Browse workspace structure, projects, and documents to locate relevant context.

getListInfo

Retrieve list details and available statuses for creating new tasks.

updateListInfo

Safely append updates to list descriptions without overwriting existing content.

getTimeEntries

View time entries and analyze time spent across projects.

createTimeEntry

Log time entries for tasks to track work progress.

readDocument

Get document details, page structure, and content with navigation.

searchDocuments

Search documents by name and space with fuzzy matching and filtering.

updateDocumentPage

Update document pages with replace or append modes.

createDocumentOrPage

Create new documents with a first page or add pages to existing documents.