Labsco
nicholasbester logo

Clickup CLI MCP Server

★ 29

from nicholasbester

An CLI and MCP server optimised for LLMs for ClickUp API

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#devops#git#translation#project-mgmt

clickup-cli

clickup-cli

A CLI for the ClickUp API, optimized for AI agents and human users.
Covers all ~130 endpoints across 28 resource groups and 4 utility commands.

Glama MCP Documentation

Why?

ClickUp's API responses are massive. A single task list query returns deeply nested JSON — statuses, assignees, priorities, custom fields, checklists, dependencies — easily 12,000+ tokens for just 5 tasks. For AI agents (Claude Code, Cursor, Copilot, etc.) operating within context windows, this is a serious problem: a few API calls can consume most of an agent's available context.

clickup-cli solves this with token-efficient output by default:

Full API JSON for 5 tasks:  ~12,000 tokens (450 lines)
clickup-cli table output:      ~150 tokens (7 lines)
Reduction:                          ~98%

The CLI flattens nested objects, selects only essential fields, and renders compact tables. Agents get the information they need without drowning in JSON. When you need the full response, --output json is always available.

Beyond token efficiency, the clickup-cli CLI (or clkup for short) gives AI agents a simple, predictable interface to ClickUp: clickup-cli <resource> <action> [ID] [flags]. No SDK, no auth boilerplate, no JSON parsing — just shell commands with structured output.

Command Groups

GroupCommands
setupConfigure token and workspace
authwhoami, check
workspacelist, seats, plan
spacelist, get, create, update, delete
folderlist, get, create, update, delete
listlist, get, create, update, delete, add-task, remove-task
tasklist, search, get, create, update, delete, time-in-status, add-tag, remove-tag, add-dep, remove-dep, link, unlink, move, set-estimate, replace-estimates
checklistcreate, update, delete, add-item, update-item, delete-item
commentlist, create, update, delete, replies, reply
taglist, create, update, delete
fieldlist, set, unset
task-typelist
attachmentlist, upload
timelist, get, current, create, update, delete, start, stop, tags, add-tags, remove-tags, rename-tag, history
goallist, get, create, update, delete, add-kr, update-kr, delete-kr
viewlist, get, create, update, delete, tasks
memberlist
userinvite, get, update, remove
chatchannel-list, channel-create, channel-get, channel-update, channel-delete, dm, message-list, message-send, message-update, message-delete, reaction-list, reaction-add, reaction-remove, reply-list, reply-send, and more
doclist, create, get, pages, add-page, page, edit-page
webhooklist, create, update, delete
templatelist, apply-task, apply-list, apply-folder
guestinvite, get, update, remove, share-task, unshare-task, share-list, unshare-list, share-folder, unshare-folder
grouplist, create, update, delete
rolelist
sharedlist
audit-logquery
aclupdate
Utilities
statusShow current config, token (masked), workspace
completionsGenerate shell completions (bash, zsh, fish, powershell)
agent-configshow, inject — CLI reference for AI agent configs
mcpserve — MCP server for native LLM tool integration

AI Agent Integration

Two ways to connect AI agents to ClickUp:

The CLI approach is the most token-efficient way to give an agent ClickUp access. Injecting the command reference costs ~1,000 tokens once, and every command returns compact table output (~150 tokens for 5 tasks). There are no tool schemas consuming context. Works with any LLM/agent framework.

clickup-cli agent-config inject            # Auto-detects: CLAUDE.md, agent.md, .cursorrules, etc.
clickup-cli agent-config inject AGENT.md   # Or specify any file explicitly
clickup-cli agent-config show              # Preview the block

Auto-detection checks for existing files in order: CLAUDE.md, agent.md, AGENT.md, .cursorrules, .github/copilot-instructions.md. Falls back to creating CLAUDE.md if none exist.

The agent then runs CLI commands directly — the full ClickUp API in ~1,000 tokens of instructions.

Alternative: MCP Server (native tool calls)

For Claude Desktop, Cursor, and other MCP-capable tools that prefer native tool integration. Note: MCP tool schemas consume more tokens in the agent's context than the CLI reference approach.

Generate the MCP config automatically:

clickup-cli agent-config init --mcp

Or add .mcp.json to your project root manually:

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

This exposes 144 tools covering 100% of the ClickUp API as native tool calls with token-efficient compact responses. See the MCP documentation for full setup.

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. Flags and matching env vars:

FlagEnv varPurpose
--profile <name>CLICKUP_MCP_PROFILEPreset: all (default), read, safe
--read-onlyCLICKUP_MCP_READ_ONLY=1Alias for --profile read
--groups a,b,cCLICKUP_MCP_GROUPSInclude only these resource groups
--exclude-groups x,yCLICKUP_MCP_EXCLUDE_GROUPSDrop these groups
--tools t1,t2CLICKUP_MCP_TOOLSInclude only these tools by exact name
--exclude-tools t1CLICKUP_MCP_EXCLUDE_TOOLSDrop these tools

--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.

Shell Completions

# Bash
clickup-cli completions bash > ~/.bash_completion.d/clickup-cli

# Zsh
clickup-cli completions zsh > ~/.zfunc/_clickup-cli

# Fish
clickup-cli completions fish > ~/.config/fish/completions/clickup-cli.fish

# PowerShell
clickup-cli completions powershell > clickup-cli.ps1

Output Modes

FlagDescription
(default)Aligned table with essential fields
--output jsonFull API response
--output json-compactDefault fields as JSON
--output csvCSV format
-q / --quietIDs only, one per line

Exit Codes

CodeMeaning
0Success
1Client error (bad input)
2Auth/permission error (401, 403)
3Not found (404)
4Rate limited (429)
5Server error (5xx)

Other community tools in the ClickUp ecosystem — picking the right one depends on your use case:

CLIs

MCP servers

Where this project fits

Rust binary, zero runtime dependency, ~130 REST endpoints + 144 MCP tools (100% API coverage), statically linked musl build for Alpine / distroless containers, and token-efficient output tuned for LLM agents. Use this when you want one binary that covers both the CLI and MCP roles without a Node/Python toolchain.