MCP Server

The clickup-cli CLI (or clkup for short) includes a built-in Model Context Protocol server, allowing LLMs to interact with ClickUp through structured tool calls instead of shell commands.

143 tools covering 100% of the ClickUp API — every endpoint available via CLI is also available as an MCP tool.

Setup

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "clickup": {
      "command": "clickup-cli",
      "args": ["mcp", "serve"]
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "clickup": {
      "command": "clickup-cli",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Code

Add .mcp.json to your project root:

{
  "mcpServers": {
    "clickup-cli": {
      "command": "/opt/homebrew/bin/clickup-cli",
      "args": ["mcp", "serve"]
    }
  }
}

Or generate it automatically:

clickup-cli agent-config init --mcp

Note: Use the full path to clickup-cli (run which clickup-cli to find it). Use clickup-cli as the server name to avoid conflicts with other ClickUp MCP integrations.

Docker

Run the MCP server as a Docker container:

# Build
docker build -t clickup-cli .

# Run MCP server (stdio)
docker run -i --rm \
  -v ~/.config/clickup-cli:/root/.config/clickup-cli \
  clickup-cli mcp serve

Or configure with environment variable:

docker run -i --rm \
  -e CLICKUP_TOKEN=pk_your_token \
  -e CLICKUP_WORKSPACE=your_workspace_id \
  clickup-cli mcp serve

Use in .mcp.json:

{
  "mcpServers": {
    "clickup-cli": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "CLICKUP_TOKEN=pk_your_token", "-e", "CLICKUP_WORKSPACE=your_workspace_id", "clickup-cli", "mcp", "serve"]
    }
  }
}

Prerequisites

Run clickup-cli setup --token pk_your_token first, or create a project-level .clickup.toml:

clickup-cli agent-config init --token pk_your_token --workspace 12345 --mcp

This creates both .clickup.toml (auth config) and .mcp.json (MCP server config) in one command.

Limiting MCP tools

By default clickup-cli mcp serve exposes all 143 tools. You can restrict this at startup to shrink the LLM’s context and enforce access control. The server also logs the active filter to stderr on startup (e.g. MCP: profile=read, exposing 52/143 tools), so you can verify the configuration at a glance. Flags and matching env vars:

--read-only agent:

{
  "mcpServers": {
    "clickup": {
      "command": "clickup-cli",
      "args": ["mcp", "serve", "--read-only"]
    }
  }
}

Task-focused agent (task + comment + time groups only):

{
  "mcpServers": {
    "clickup": {
      "command": "clickup-cli",
      "args": ["mcp", "serve", "--groups", "task,comment,time"]
    }
  }
}

Filtered tools are rejected at tools/call as well as hidden from tools/list, so a misbehaving agent can’t smuggle a destructive call past the filter.

vs. ClickUp’s official MCP server

ClickUp ships its own MCP server. Both are valid, aimed at different use cases.

Pick this project when you want local execution, personal-token auth, complete API coverage, and the ability to shape a read-only or task-focused agent via the filter flags.

Pick ClickUp’s official when you want OAuth (multi-user), zero install, or a curated tool set that ClickUp maintains.

Available Tools (143)

All tool names are prefixed with clickup_ (e.g., clickup_task_list).

How It Works

The MCP server uses JSON-RPC 2.0 over stdio. It reads requests from stdin and writes responses to stdout. The server uses the same HTTP client and authentication as the CLI commands, and returns token-efficient compact responses — the same field flattening as the CLI’s table output, but as JSON. Status objects, priority objects, assignee arrays, and timestamps are all flattened to simple values.

LLM ↔ JSON-RPC (stdio) ↔ clickup-cli mcp serve ↔ ClickUp API
                                ↓
                        Compact JSON response
                   (flattened, essential fields only)

CLI vs MCP

The CLI approach is preferred for token efficiency — it costs ~1,000 tokens once for the full command reference, while MCP tool schemas consume significantly more context per session. Both have 100% API coverage with token-efficient output.

Use MCP when your tool requires native tool integration (e.g., Claude Desktop doesn’t run shell commands).

Both modes deliver ~98% token reduction compared to raw API JSON. Both use the same authentication and config file.

← Command Reference · Home →