Clickup CLI MCP Server

Un servidor CLI y MCP optimizado para LLMs para la API de ClickUp

Documentación

clickup-cli

Una CLI para la API de ClickUp, optimizada para agentes de IA y usuarios humanos.
Cubre los ~130 endpoints en 28 grupos de recursos y 4 comandos de utilidad.

Documentación

¿Por qué?

Las respuestas de la API de ClickUp son enormes. Una simple consulta de lista de tareas devuelve JSON profundamente anidado — estados, asignados, prioridades, campos personalizados, listas de verificación, dependencias — fácilmente 12,000+ tokens por solo 5 tareas. Para agentes de IA (Claude Code, Cursor, Copilot, etc.) que operan dentro de ventanas de contexto, esto es un problema serio: unas pocas llamadas a la API pueden consumir la mayor parte del contexto disponible de un agente.

clickup-cli resuelve esto con salida eficiente en tokens por defecto:

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

La CLI aplana objetos anidados, selecciona solo campos esenciales y renderiza tablas compactas. Los agentes obtienen la información que necesitan sin ahogarse en JSON. Cuando necesitas la respuesta completa, --output json está siempre disponible.

Más allá de la eficiencia de tokens, la CLI clickup-cli (o clkup para abreviar) brinda a los agentes de IA una interfaz simple y predecible hacia ClickUp: clickup-cli <resource> <action> [ID] [flags]. Sin SDK, sin código repetitivo de autenticación, sin análisis de JSON — solo comandos de shell con salida estructurada.

Instalación

npm (cualquier plataforma con Node.js)

npm install -g @nick.bester/clickup-cli

Homebrew (macOS o Linux)

brew tap nicholasbester/clickup-cli
brew install clickup-cli

Para actualizar a la última versión:

brew upgrade clickup-cli

Funciona también en Linux — el tap incluye binarios nativos de Linux x86_64 y arm64.

macOS / Linux (binario precompilado)

Descarga la última versión para tu plataforma:

# macOS Apple Silicon (M1/M2/M3/M4)
curl -L https://github.com/nicholasbester/clickup-cli/releases/latest/download/clickup-macos-arm64.tar.gz | tar xz
sudo mv clickup-cli clkup /usr/local/bin/

# macOS Intel
curl -L https://github.com/nicholasbester/clickup-cli/releases/latest/download/clickup-macos-x86_64.tar.gz | tar xz
sudo mv clickup-cli clkup /usr/local/bin/

# Linux x86_64
curl -L https://github.com/nicholasbester/clickup-cli/releases/latest/download/clickup-linux-x86_64.tar.gz | tar xz
sudo mv clickup-cli clkup /usr/local/bin/

# Linux ARM64
curl -L https://github.com/nicholasbester/clickup-cli/releases/latest/download/clickup-linux-arm64.tar.gz | tar xz
sudo mv clickup-cli clkup /usr/local/bin/

Alpine / musl Linux:

curl -L https://github.com/nicholasbester/clickup-cli/releases/latest/download/clickup-linux-x86_64-musl.tar.gz | tar xz
mv clickup-cli clkup /usr/local/bin/

Arch Linux (AUR)

yay -S clickup-cli-bin
# or
paru -S clickup-cli-bin

clickup-cli-bin envuelve los binarios Linux precompilados — no se requiere toolchain de Rust. Se actualiza automáticamente en cada versión.

Windows

Descarga clickup-windows-x86_64.zip desde la última versión, extráelo y agrega clickup-cli.exe (y opcionalmente clkup.exe) a tu PATH.

Desde crates.io (cualquier plataforma)

Requiere Rust 1.70+:

cargo install clickup-cli

Docker

docker build -t clickup-cli .
docker run -i --rm -e CLICKUP_TOKEN=pk_xxx -e CLICKUP_WORKSPACE=12345 clickup-cli mcp serve

Desde el código fuente

git clone https://github.com/nicholasbester/clickup-cli.git
cd clickup-cli
cargo install --path .

Dos binarios

Cada método de instalación incluye dos binarios con comportamiento idéntico:

clickup-cli — nombre canónico (úsalo en scripts, CI, configuraciones MCP)
clkup — alias corto, práctico para escritura interactiva diaria

Elige el que prefieras; ambos aceptan las mismas banderas y subcomandos.

Verificar instalación

clickup-cli --version
# or
clkup --version

Inicio Rápido

# Configure your API token
clickup-cli setup

# Or non-interactive
clickup-cli setup --token pk_your_token_here

# Verify
clickup-cli auth whoami

Ejemplos de Uso

# Hierarchy navigation
clickup-cli workspace list
clickup-cli space list
clickup-cli folder list --space 12345
clickup-cli list list --folder 67890

# Task management
clickup-cli task list --list 12345
clickup-cli task create --list 12345 --name "My Task" --priority 3
clickup-cli task get abc123
clickup-cli task update abc123 --status "in progress"
clickup-cli task search --status "in progress" --assignee 44106202

# Comments and collaboration
clickup-cli comment list --task abc123
clickup-cli comment create --task abc123 --text "Looking good!"
clickup-cli comment reply COMMENT_ID --text "Thanks!"

# Time tracking
clickup-cli time start --task abc123 --description "Working on feature"
clickup-cli time stop
clickup-cli time list --start-date 2026-03-01 --end-date 2026-03-31

# Goals and views
clickup-cli goal list
clickup-cli view list --space 12345
clickup-cli view tasks VIEW_ID

# Tags and custom fields
clickup-cli tag list --space 12345
clickup-cli field list --list 12345
clickup-cli field set FIELD_ID --value "some value" TASK_ID

# Chat (v3)
clickup-cli chat channel-list
clickup-cli chat message-send --channel CHAN_ID --text "Hello team"

# Docs (v3)
clickup-cli doc list
clickup-cli doc get DOC_ID

# Output modes
clickup-cli task list --list 12345 --output json        # Full JSON
clickup-cli task list --list 12345 --output json-compact # Default fields as JSON
clickup-cli task list --list 12345 --output csv          # CSV
clickup-cli task list --list 12345 -q                    # IDs only
clickup-cli task list --list 12345 --fields id,name,status  # Custom fields

# Auto-detect task ID from git branch (on a branch like feat/CU-abc123-foo)
clickup-cli task get                                     # Resolves to abc123 from the branch
clickup-cli task update --status "in progress"
clickup-cli comment create --text "Looking good!"
clickup-cli field set FIELD_ID --value "some value"

Detección automática de ID de tarea desde la rama git

Cuando una rama con seguimiento git sigue una convención de nomenclatura común, clickup-cli resuelve el ID de tarea automáticamente:

IDs predeterminados de ClickUp — feat/CU-abc123-foo → abc123
IDs de tarea personalizados — PROJ-42-add-login → PROJ-42 (inyecta automáticamente custom_task_ids=true&team_id=<ws>)

Los prefijos se eliminan sin distinguir mayúsculas: feature/, feat/, fix/, hotfix/, bugfix/, release/, chore/, docs/, refactor/, test/, ci/, perf/, build/, style/. Las coincidencias de ID personalizado cuyo prefijo es FEATURE, FEAT, BUGFIX, BUG, FIX, HOTFIX, RELEASE, CHORE, DOCS, DOC, REFACTOR, TEST, CI, PERF, BUILD, STYLE, WIP o TMP son rechazadas.

Orden de resolución (mayor prioridad primero): argumento CLI explícito → variable de entorno CLICKUP_TASK_ID → rama git. El CU-abc123 explícito se elimina de forma transparente a abc123. Los comandos destructivos o ambiguos (task delete, task link, task unlink, guest share-task, guest unshare-task) nunca se auto-detectan — pasa el ID explícitamente.

Desactívalo para una invocación con CLICKUP_GIT_DETECT=0, o permanentemente en la configuración:

[git]
enabled = false    # disable branch detection
verbose = false    # suppress the "resolved task X from branch Y" breadcrumb

Grupos de Comandos

Grupo	Comandos
`setup`	Configurar token y workspace
`auth`	whoami, check, login, logout, status
`workspace`	list, seats, plan
`space`	list, get, create, update, delete
`folder`	list, get, create, update, delete
`list`	list, get, create, update, delete, add-task, remove-task
`task`	list, search, get, create, update, delete, time-in-status, add-tag, remove-tag, add-dep, remove-dep, link, unlink, move, set-estimate, replace-estimates
`checklist`	create, update, delete, add-item, update-item, delete-item
`comment`	list, create, update, delete, replies, reply
`tag`	list, create, update, delete
`field`	list, set, unset
`task-type`	list
`attachment`	list, upload
`time`	list, get, current, create, update, delete, start, stop, tags, add-tags, remove-tags, rename-tag, history
`goal`	list, get, create, update, delete, add-kr, update-kr, delete-kr
`view`	list, get, create, update, delete, tasks
`member`	list
`user`	invite, get, update, remove
`chat`	channel-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, y más
`doc`	list, create, get, pages, add-page, page, edit-page
`webhook`	list, create, update, delete
`template`	list, apply-task, apply-list, apply-folder
`guest`	invite, get, update, remove, share-task, unshare-task, share-list, unshare-list, share-folder, unshare-folder
`group`	list, create, update, delete
`role`	list
`shared`	list
`audit-log`	query
`acl`	update
Utilidades
`status`	Mostrar configuración actual, token (enmascarado), workspace
`completions`	Generar completaciones de shell (bash, zsh, fish, powershell)
`agent-config`	show, inject — referencia CLI para configuraciones de agentes de IA
`mcp`	serve — servidor MCP para integración nativa de herramientas LLM

Integración con Agentes de IA

Dos formas de conectar agentes de IA a ClickUp:

Recomendado: Modo CLI (comandos de shell)

El enfoque CLI es la forma más eficiente en tokens para dar acceso a ClickUp a un agente. Inyectar la referencia de comandos cuesta ~1,000 tokens una vez, y cada comando devuelve salida de tabla compacta (~150 tokens para 5 tareas). No hay esquemas de herramientas que consuman contexto. Funciona con cualquier framework de LLM/agente.

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

La auto-detección verifica archivos existentes en orden: CLAUDE.md, agent.md, AGENT.md, .cursorrules, .github/copilot-instructions.md. Si no existe ninguno, crea CLAUDE.md como respaldo.

El agente luego ejecuta comandos CLI directamente — la API completa de ClickUp en ~1,000 tokens de instrucciones.

Alternativa: Servidor MCP (llamadas nativas de herramientas)

Para Claude Desktop, Cursor y otras herramientas compatibles con MCP que prefieren integración nativa de herramientas. Nota: los esquemas de herramientas MCP consumen más tokens en el contexto del agente que el enfoque de referencia CLI.

Genera la configuración MCP automáticamente:

clickup-cli agent-config init --mcp

O agrega .mcp.json manualmente a la raíz de tu proyecto:

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

Esto expone 144 herramientas que cubren el 100% de la API de ClickUp como llamadas nativas de herramientas con respuestas compactas eficientes en tokens. Consulta la documentación de MCP para la configuración completa.

Limitando herramientas MCP

Por defecto, clickup-cli mcp serve expone las 144 herramientas. Puedes restringir esto al inicio para reducir el contexto del LLM y aplicar control de acceso. Banderas y variables de entorno correspondientes:

Bandera	Variable de entorno	Propósito
`--profile <name>`	`CLICKUP_MCP_PROFILE`	Preajuste: `all` (predeterminado), `read`, `safe`
`--read-only`	`CLICKUP_MCP_READ_ONLY=1`	Alias para `--profile read`
`--groups a,b,c`	`CLICKUP_MCP_GROUPS`	Incluir solo estos grupos de recursos
`--exclude-groups x,y`	`CLICKUP_MCP_EXCLUDE_GROUPS`	Eliminar estos grupos
`--tools t1,t2`	`CLICKUP_MCP_TOOLS`	Incluir solo estas herramientas por nombre exacto
`--exclude-tools t1`	`CLICKUP_MCP_EXCLUDE_TOOLS`	Eliminar estas herramientas

Agente --read-only:

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

Agente enfocado en tareas (solo grupos de tarea + comentario + tiempo):

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

Las herramientas filtradas se rechazan en tools/call y también se ocultan de tools/list, por lo que un agente con mal comportamiento no puede colar una llamada destructiva más allá del filtro.

Configuración

Archivos de Configuración

Nivel	Archivo	Caso de uso
Proyecto	`.clickup.toml`	Token/workspace por proyecto (repos de equipo, CI)
Global	`~/.config/clickup-cli/config.toml`	Predeterminado personal

Crea una configuración a nivel de proyecto:

clickup-cli agent-config init --token pk_xxx --workspace 12345

Esto crea .clickup.toml en el directorio actual. Agrégalo a .gitignore si contiene un token. La configuración de proyecto tiene prioridad sobre la global.

OAuth (trae tu propia aplicación)

clickup-cli auth login admite una aplicación BYO de ClickUp usando CLICKUP_OAUTH_CLIENT_ID y CLICKUP_OAUTH_CLIENT_SECRET (o --client-id / --client-secret). Registra la redirección exacta http://127.0.0.1:53682/callback; --redirect-port cambia el puerto. Usa --no-browser para imprimir la URL, --keyring para almacenamiento opt-in del sistema operativo, auth status para la identidad/tipo/fuente/workspace efectivos y auth logout para eliminar credenciales almacenadas. No se incluye ningún secreto de mantenedor ni proxy.

La aceptación de loopback en vivo y la verificación de respuesta de token siguen pendientes. Consulta autenticación y almacenamiento para registro, limitaciones headless/SSH, funciones de compilación de keyring, alcance de logout y requisitos de aceptación del propietario.

Resolución de Token (mayor prioridad gana)

Bandera CLI --token (personal por defecto; --token-kind oauth selecciona OAuth)
Variable de entorno CLICKUP_TOKEN (personal)
Variable de entorno CLICKUP_OAUTH_TOKEN (OAuth)
.clickup.toml ancestro más cercano con credenciales
Configuración global del SO (~/.config/clickup-cli/config.toml en Linux)

[auth] kind = "oauth" selecciona OAuth; el tipo omitido por defecto es personal. El almacenamiento en archivo es el predeterminado; storage = "keychain" selecciona explícitamente el llavero del SO y falla si no está disponible. Los tokens personales envían Authorization: <token>; los tokens OAuth envían Authorization: Bearer <token>, incluyendo cargas y MCP. CLICKUP_CONFIG selecciona una única ruta de configuración y desactiva el descubrimiento, útil para entornos aislados.

Resolución de Workspace

Bandera CLI --workspace
Variable de entorno CLICKUP_WORKSPACE
.clickup.toml (nivel de proyecto)
~/.config/clickup-cli/config.toml (global)

Verificar Configuración Actual

clickup-cli status

clickup-cli vX.Y.Z

Config:    ~/.config/clickup-cli/config.toml
Token:     pk_abc...wxyz
Workspace: 1234567

Completaciones de Shell

# 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

Modos de Salida

Bandera	Descripción
(predeterminado)	Tabla alineada con campos esenciales
`--output json`	Respuesta completa de la API
`--output json-compact`	Campos predeterminados como JSON
`--output csv`	Formato CSV
`-q` / `--quiet`	Solo IDs, uno por línea

Códigos de Salida

Código	Significado
0	Éxito
1	Error de cliente (entrada incorrecta) — incluye errores de uso/análisis de CLI
2	Error de autenticación/permiso (401, 403)
3	No encontrado (404)
4	Límite de tasa (429)
5	Error de servidor (5xx)

Proyectos relacionados

Otras herramientas de la comunidad en el ecosistema ClickUp — elegir la correcta depende de tu caso de uso:

CLIs

triptechtravel/clickup-cli — CLI de Go enfocado en flujos de trabajo para desarrolladores. Detecta automáticamente los IDs de tareas a partir de los nombres de ramas de git (CU-abc123), con integración estrecha con GitHub PR.
dang3r/clickupy — CLI y biblioteca de Python. Tiene un modo de montaje FUSE si quieres explorar ClickUp como un sistema de archivos.
code-gorilla-au/clickup-cli — otro CLI de Go.
techlove/gitclick — sincronización de alcance limitado entre ClickUp y GitHub PR.

Servidores MCP

MCP oficial de ClickUp — alojado, con OAuth y un conjunto de herramientas seleccionadas.
taazkareem/clickup-mcp-server, hauptsacheNet/clickup-mcp, Nazruden/clickup-mcp-server — servidores MCP de Node/TypeScript mantenidos por la comunidad.

Dónde encaja este proyecto

Binario de Rust, sin dependencias en tiempo de ejecución, ~130 endpoints REST + 144 herramientas MCP (100% de cobertura de API), compilación estática con musl para contenedores Alpine / distroless, y salida optimizada en tokens para agentes LLM. Úsalo cuando quieras un solo binario que cubra tanto los roles de CLI como de MCP sin necesidad de un entorno Node/Python.

Historial de estrellas

Licencia

Apache-2.0