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.

144 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 144 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/144 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 (144)

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

Pagination

Tools backed by paginated ClickUp endpoints expose pagination controls. Fifteen tools currently support pagination, across four styles:

The contract is opt-in and non-breaking:

• No pagination args passed. The tool’s response is identical to the pre-pagination shape — a bare compact array. Existing clients see no change.

• Any pagination arg passed. The response becomes an envelope:

  {
    "items": [ /* compact items, same shape as before */ ],
    "pagination": {
      "style": "page",                 // or "cursor", "start_id", "body"
      "page": 0,                       // page-style only
      "last_page": false,              // page-style only
      "next_cursor": "...",            // cursor-style only, omitted when exhausted
      "next_start": 1700000000,        // start_id-style only, omitted when exhausted
      "next_start_id": "...",          // start_id-style only, omitted when exhausted
      "next_page_timestamp": 1700000,  // body-style only, omitted when exhausted
      "page_direction": "NEXT",        // body-style only, echoes caller input
      "has_more": true,
      "returned": 42,
      "all": false
    }
  }
  

With all=true the server walks pages until natural termination:

• page-style: ClickUp reports last_page=true.
• cursor-style: next_cursor is null or empty.
• start-id-style: the returned page is shorter than ClickUp’s documented page size (25).
• body-style: the server returns an empty response.

…or limit is reached. A hard cap of 100 pages prevents runaway loops on misbehaving endpoints.

has_more reports purely whether the server has additional pages — not whether limit truncated the response. A limit-capped call with more results available still surfaces next_cursor / next_start / next_page_timestamp so callers who want to continue from where the server left off (rather than from where the helper cut the buffer) have what they need.

The CLI side mirrors this contract on every paginated command via the same set of global flags: --all, --page / --cursor / --start + --start-id, and --limit. CLI output stays as plain table/JSON/CSV — no envelope — but pagination state is honoured identically.

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 →