Clickup CLI MCP Server

Um servidor CLI e MCP otimizado para LLMs para a API do ClickUp

Documentação

clickup-cli

Uma CLI para a API do ClickUp, otimizada para agentes de IA e usuários humanos.
Cobre todos os ~130 endpoints em 28 grupos de recursos e 4 comandos utilitários.

Documentação

Por quê?

As respostas da API do ClickUp são enormes. Uma simples consulta de lista de tarefas retorna JSON profundamente aninhado — status, responsáveis, prioridades, campos personalizados, checklists, dependências — facilmente 12.000+ tokens para apenas 5 tarefas. Para agentes de IA (Claude Code, Cursor, Copilot, etc.) operando dentro de janelas de contexto, isso é um problema sério: algumas chamadas de API podem consumir a maior parte do contexto disponível de um agente.

O clickup-cli resolve isso com saída eficiente em tokens por padrão:

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

A CLI achata objetos aninhados, seleciona apenas campos essenciais e renderiza tabelas compactas. Os agentes obtêm as informações de que precisam sem se afogar em JSON. Quando você precisa da resposta completa, --output json está sempre disponível.

Além da eficiência de tokens, a CLI clickup-cli (ou clkup para abreviar) dá aos agentes de IA uma interface simples e previsível para o ClickUp: clickup-cli <resource> <action> [ID] [flags]. Sem SDK, sem código padrão de autenticação, sem análise de JSON — apenas comandos de shell com saída estruturada.

Instalação

npm (qualquer plataforma com Node.js)

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

Homebrew (macOS ou Linux)

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

Para atualizar para a versão mais recente:

brew upgrade clickup-cli

Funciona também no Linux — o tap inclui binários nativos x86_64 e arm64 para Linux.

macOS / Linux (binário pré-compilado)

Baixe a versão mais recente para sua 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 empacota os binários Linux pré-compilados — nenhuma toolchain Rust necessária. Atualizado automaticamente a cada lançamento.

Windows

Baixe clickup-windows-x86_64.zip do último lançamento, extraia e adicione clickup-cli.exe (e opcionalmente clkup.exe) ao seu PATH.

Do crates.io (qualquer plataforma)

Requer 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

A partir do código-fonte

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

Dois binários

Cada método de instalação entrega dois binários com comportamento idêntico:

clickup-cli — nome canônico (use este em scripts, CI, configurações MCP)
clkup — alias curto, prático para digitação interativa diária

Escolha o que preferir; ambos aceitam os mesmos flags e subcomandos.

Verificar instalação

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

Início 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

Exemplos 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"

Detecção automática de ID de tarefa a partir do branch git

Quando um branch rastreado pelo git segue uma convenção de nomenclatura comum, clickup-cli resolve o ID da tarefa automaticamente:

IDs padrão do ClickUp — feat/CU-abc123-foo → abc123
IDs de tarefa personalizados — PROJ-42-add-login → PROJ-42 (injeção automática de custom_task_ids=true&team_id=<ws>)

Prefixos removidos sem diferenciar maiúsculas/minúsculas: feature/, feat/, fix/, hotfix/, bugfix/, release/, chore/, docs/, refactor/, test/, ci/, perf/, build/, style/. Correspondências de ID personalizado cujo prefixo seja FEATURE, FEAT, BUGFIX, BUG, FIX, HOTFIX, RELEASE, CHORE, DOCS, DOC, REFACTOR, TEST, CI, PERF, BUILD, STYLE, WIP ou TMP são rejeitadas.

Ordem de resolução (maior prioridade primeiro): argumento CLI explícito → variável de ambiente CLICKUP_TASK_ID → branch git. CU-abc123 explícito é removido de forma transparente para abc123. Comandos destrutivos ou ambíguos (task delete, task link, task unlink, guest share-task, guest unshare-task) nunca fazem detecção automática — passe o ID explicitamente.

Desative para uma única invocação com CLICKUP_GIT_DETECT=0, ou permanentemente na configuração:

[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 e 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, e mais
`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
Utilitários
`status`	Mostrar configuração atual, token (mascarado), workspace
`completions`	Gerar completions de shell (bash, zsh, fish, powershell)
`agent-config`	show, inject — referência de CLI para configurações de agentes de IA
`mcp`	serve — servidor MCP para integração nativa de ferramentas LLM

Integração com Agentes de IA

Duas maneiras de conectar agentes de IA ao ClickUp:

Recomendado: Modo CLI (comandos de shell)

A abordagem CLI é a maneira mais eficiente em tokens de dar a um agente acesso ao ClickUp. Injetar a referência de comandos custa ~1.000 tokens uma vez, e cada comando retorna saída de tabela compacta (~150 tokens para 5 tarefas). Não há schemas de ferramentas consumindo contexto. Funciona com qualquer 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

A detecção automática verifica arquivos existentes nesta ordem: CLAUDE.md, agent.md, AGENT.md, .cursorrules, .github/copilot-instructions.md. Se nenhum existir, cria CLAUDE.md como fallback.

O agente então executa comandos CLI diretamente — a API completa do ClickUp em ~1.000 tokens de instruções.

Alternativa: Servidor MCP (chamadas nativas de ferramentas)

Para Claude Desktop, Cursor e outras ferramentas compatíveis com MCP que preferem integração nativa de ferramentas. Observação: schemas de ferramentas MCP consomem mais tokens no contexto do agente do que a abordagem de referência CLI.

Gere a configuração MCP automaticamente:

clickup-cli agent-config init --mcp

Ou adicione .mcp.json manualmente à raiz do seu projeto:

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

Isso expõe 144 ferramentas cobrindo 100% da API do ClickUp como chamadas nativas de ferramentas com respostas compactas e eficientes em tokens. Veja a documentação MCP para configuração completa.

Limitando ferramentas MCP

Por padrão, clickup-cli mcp serve expõe todas as 144 ferramentas. Você pode restringir isso na inicialização para reduzir o contexto do LLM e aplicar controle de acesso. Flags e variáveis de ambiente correspondentes:

Flag	Variável de ambiente	Finalidade
`--profile <name>`	`CLICKUP_MCP_PROFILE`	Predefinição: `all` (padrão), `read`, `safe`
`--read-only`	`CLICKUP_MCP_READ_ONLY=1`	Alias para `--profile read`
`--groups a,b,c`	`CLICKUP_MCP_GROUPS`	Incluir apenas estes grupos de recursos
`--exclude-groups x,y`	`CLICKUP_MCP_EXCLUDE_GROUPS`	Remover estes grupos
`--tools t1,t2`	`CLICKUP_MCP_TOOLS`	Incluir apenas estas ferramentas por nome exato
`--exclude-tools t1`	`CLICKUP_MCP_EXCLUDE_TOOLS`	Remover estas ferramentas

Agente --read-only:

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

Agente focado em tarefas (apenas grupos de tarefa + comentário + tempo):

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

Ferramentas filtradas são rejeitadas em tools/call e também ocultadas de tools/list, então um agente mal comportado não pode contrabandear uma chamada destrutiva além do filtro.

Configuração

Arquivos de Configuração

Nível	Arquivo	Caso de uso
Projeto	`.clickup.toml`	Token/workspace por projeto (repos de equipe, CI)
Global	`~/.config/clickup-cli/config.toml`	Padrão pessoal

Crie uma configuração de nível de projeto:

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

Isso cria .clickup.toml no diretório atual. Adicione-o ao .gitignore se contiver um token. A configuração de projeto tem prioridade sobre a configuração global.

OAuth (traga seu próprio aplicativo)

clickup-cli auth login suporta um aplicativo ClickUp BYO usando CLICKUP_OAUTH_CLIENT_ID e CLICKUP_OAUTH_CLIENT_SECRET (ou --client-id / --client-secret). Registre o redirect exato http://127.0.0.1:53682/callback; --redirect-port altera a porta. Use --no-browser para imprimir a URL, --keyring para armazenamento opcional no SO, auth status para a identidade/tipo/origem/workspace efetivos e auth logout para remover credenciais armazenadas. Nenhum segredo de mantenedor ou proxy é incluído.

Aceitação de loopback ao vivo e verificação de resposta de token permanecem pendentes. Veja autenticação e armazenamento para registro, limitações headless/SSH, recursos de build de keyring, escopo de logout e requisitos de aceitação do proprietário.

Resolução de Token (maior prioridade vence)

Flag CLI --token (pessoal por padrão; --token-kind oauth seleciona OAuth)
Variável de ambiente CLICKUP_TOKEN (pessoal)
Variável de ambiente CLICKUP_OAUTH_TOKEN (OAuth)
.clickup.toml ancestral mais próximo com credenciais
Configuração global do SO (~/.config/clickup-cli/config.toml no Linux)

[auth] kind = "oauth" seleciona OAuth; tipo omitido assume pessoal. Armazenamento em arquivo é o padrão; storage = "keychain" seleciona explicitamente o keyring do SO e falha se indisponível. Tokens pessoais enviam Authorization: <token>; tokens OAuth enviam Authorization: Bearer <token>, incluindo uploads e MCP. CLICKUP_CONFIG seleciona um único caminho de configuração e desativa a descoberta, útil para ambientes isolados.

Resolução de Workspace

Flag CLI --workspace
Variável de ambiente CLICKUP_WORKSPACE
.clickup.toml (nível de projeto)
~/.config/clickup-cli/config.toml (global)

Verificar Configuração Atual

clickup-cli status

clickup-cli vX.Y.Z

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

Completions 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 Saída

Flag	Descrição
(padrão)	Tabela alinhada com campos essenciais
`--output json`	Resposta completa da API
`--output json-compact`	Campos padrão como JSON
`--output csv`	Formato CSV
`-q` / `--quiet`	Apenas IDs, um por linha

Códigos de Saída

Código	Significado
0	Sucesso
1	Erro de cliente (entrada inválida) — inclui erros de uso/análise da CLI
2	Erro de autenticação/permissão (401, 403)
3	Não encontrado (404)
4	Limite de taxa excedido (429)
5	Erro de servidor (5xx)

Projetos relacionados

Outras ferramentas da comunidade no ecossistema ClickUp — escolher a certa depende do seu caso de uso:

CLIs

triptechtravel/clickup-cli — CLI em Go focado em fluxos de trabalho para desenvolvedores. Detecta automaticamente IDs de tarefas a partir de nomes de branches git (CU-abc123), integração estreita com GitHub PR.
dang3r/clickupy — CLI em Python + biblioteca. Possui um modo de montagem FUSE se você quiser navegar pelo ClickUp como um sistema de arquivos.
code-gorilla-au/clickup-cli — outro CLI em Go.
techlove/gitclick — sincronização ClickUp ↔ GitHub PR de escopo restrito.

Servidores MCP

MCP oficial do ClickUp — hospedado, OAuth, conjunto de ferramentas curado.
taazkareem/clickup-mcp-server, hauptsacheNet/clickup-mcp, Nazruden/clickup-mcp-server — servidores MCP Node/TypeScript mantidos pela comunidade.

Onde este projeto se encaixa

Binário em Rust, zero dependência em tempo de execução, ~130 endpoints REST + 144 ferramentas MCP (100% de cobertura da API), build musl estaticamente vinculado para contêineres Alpine / distroless, e saída eficiente em tokens ajustada para agentes LLM. Use isto quando você quiser um único binário que cubra tanto os papéis de CLI quanto de MCP sem uma toolchain Node/Python.

Histórico de Estrelas

Licença

Apache-2.0