clickup-mcp

Servidor MCP ClickUp leve com 35 ferramentas. Respostas otimizadas em tokens reduzem a verbosidade da API em mais de 95% (3500 caracteres → 160). Tarefas, comentários, listas de verificação, tags, dependências.

GitHub

Documentação

clickup-mcp

Servidor MCP leve do ClickUp focado em gerenciamento de tarefas. 40 ferramentas com respostas otimizadas em tokens - as respostas da API são automaticamente reduzidas de milhares de caracteres para o essencial.

Por que este servidor?

A API do ClickUp retorna JSON extremamente verboso. Este servidor o reduz:

Resposta	Antes	Depois	Redução
`clickup_whoami`	~3.500 caracteres	~160 caracteres	95%
`clickup_create_comment`	~1.500 caracteres	~38 caracteres	97%

Menos tokens = respostas mais rápidas, custos menores, mais contexto para sua IA.

Instalação

npm install -g @cavort-it-systems/clickup-mcp

Ou execute diretamente:

npx @cavort-it-systems/clickup-mcp

Configuração

Claude Code CLI

claude mcp add clickup -e CLICKUP_API_TOKEN=your-token -- npx @cavort-it-systems/clickup-mcp

Claude Desktop / Manual

Adicione à sua configuração MCP (~/.claude.json ou configurações do Claude Desktop):

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["@cavort-it-systems/clickup-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "your-token"
      }
    }
  }
}

A partir do código-fonte

git clone https://github.com/cvrt-jh/clickup-mcp.git
cd clickup-mcp
pnpm install && pnpm build

Depois configure com o caminho compilado:

claude mcp add clickup -e CLICKUP_API_TOKEN=your-token -- node /path/to/clickup-mcp/build/index.js

IDs de tarefa personalizados

Toda ferramenta que aceita um task_id também aceita o ID personalizado (DEV-1217), não apenas o interno (86caqr85m). O servidor adiciona o custom_task_ids=true&team_id=... automaticamente. O ID do workspace vem de CLICKUP_TEAM_ID, ou, se não definido, do único workspace do token (consultado uma vez). Um token com acesso a vários workspaces deve definir CLICKUP_TEAM_ID.

Obtenha seu token de API

Vá em ClickUp Settings > Apps
Gere um Personal API Token
Defina como CLICKUP_API_TOKEN

Redução de resposta

Todas as respostas são automaticamente reduzidas para economizar tokens. A API do ClickUp retorna JSON extremamente verboso - este servidor o reduz ao que importa.

clickup_whoami - de ~3.500 caracteres para ~160:

// Before (ClickUp API raw)
{"user":{"id":12345678,"username":"Jane Doe","email":"jane@example.com","color":"#0388d1",
"profilePicture":"https://attachments.clickup.com/...","initials":"JD",
"week_start_day":1,"global_font_support":true,"timezone":"Europe/Berlin"},
"teams":{"teams":[{"id":"99999999","name":"My Workspace","color":"#40BC86",
"avatar":"https://attachments2.clickup.com/...?Expires=...&Key-Pair-Id=...&Signature=...",
"members":[{"user":{"id":11111111,"username":"Bob Smith","email":"bob@example.com",
"color":"#aa2fff","profilePicture":null,"initials":"BS","role":4,"role_subtype":2,
"role_key":"guest","custom_role":null,"last_active":"...","date_joined":"...",
"date_invited":"..."},"invited_by":{"id":22222222,...},
"can_see_time_spent":true,...}, ...]}]}}

// After (slimmed)
{"id":12345678,"username":"Jane Doe","email":"jane@example.com",
"timezone":"Europe/Berlin","workspaces":[{"id":"99999999",
"name":"My Workspace","member_count":4}]}

clickup_create_comment - de ~1.500 caracteres para 38:

// Before
{"id":90150191300876,"hist_id":"...","date":1770053982842,
"version":{"object_type":"comment","object_id":"...","workspace_id":99999999,
"operation":"c","data":{"context":{"root_parent_type":1,"is_chat":false,
"audit_context":{"userid":12345678,"current_time":...,"route":"*"},...},...},...}}

// After
{"id":90150191300876,"date":1770053982842}

O que é removido:

Campo	Onde	Por quê
`features{}`	espaços	~50 linhas de flags booleanas por espaço
`sharing{}`, `permission_level`	tarefas	Configuração interna de acesso, não útil
`watchers[]`	tarefas	Geralmente igual aos responsáveis
Objetos completos de usuário	em todo lugar	Reduzidos a `{id, username, email}`
`profilePicture`, `initials`, `color`	usuários	Metadados visuais, não úteis para LLMs
Blobs de `version{}`	criação de comentários/respostas	Dados internos de versionamento
`invited_by`, `profileInfo`	membros	Metadados de convite
JSON com indentação	todas as respostas	Saída compacta em linha única
Arrays vazios	tarefas	`checklists`, `dependencies`, `custom_fields` omitidos quando vazios

Ferramentas (40)

Navegação (7)

clickup_whoami - Usuário atual + workspaces
clickup_get_spaces - Espaços no workspace
clickup_get_folders - Pastas no espaço
clickup_get_lists - Listas na pasta ou espaço
clickup_get_list - Detalhes de uma única lista
clickup_create_list - Criar lista na pasta ou espaço
clickup_delete_list - Excluir uma lista (permanente)

CRUD de tarefas (5)

clickup_get_task - Obter tarefa por ID
clickup_create_task - Criar tarefa com todos os campos
clickup_update_task - Atualizar qualquer campo da tarefa
clickup_get_tasks - Listar tarefas em uma lista
clickup_search_tasks - Pesquisar tarefas em todo o workspace

Campos personalizados (1)

clickup_set_custom_field - Definir valor de campo personalizado

Tags (6)

clickup_get_space_tags - Listar tags do espaço
clickup_create_space_tag - Criar tag
clickup_edit_space_tag - Editar tag
clickup_delete_space_tag - Excluir tag
clickup_add_tag_to_task - Adicionar tag a uma tarefa
clickup_remove_tag_from_task - Remover tag de uma tarefa

Checklists (6)

clickup_create_checklist - Criar checklist
clickup_edit_checklist - Editar checklist
clickup_delete_checklist - Excluir checklist
clickup_create_checklist_item - Adicionar item
clickup_edit_checklist_item - Editar item
clickup_delete_checklist_item - Excluir item

Dependências (4)

clickup_add_dependency - Adicionar dependência
clickup_delete_dependency - Remover dependência
clickup_add_task_link - Vincular tarefas
clickup_delete_task_link - Desvincular tarefas

Comentários (5)

clickup_create_comment - Adicionar comentário
clickup_get_comments - Obter comentários
clickup_update_comment - Editar/resolver comentário
clickup_create_reply - Resposta em thread
clickup_get_replies - Obter respostas

Excluir tarefa (1)

clickup_delete_task - Excluir uma tarefa

Associação a múltiplas listas (2)

clickup_add_task_to_list - Adicionar uma tarefa a uma lista adicional (multi-homing)
clickup_remove_task_from_list - Remover uma tarefa de uma lista adicional

Estas ações não movem uma tarefa. A API v2 do ClickUp não possui endpoint para mover entre listas. Verificado na API ao vivo em 2026-08-12: POST /list/{list}/task/{task} adiciona um local secundário e deixa a lista inicial inalterada, enquanto um list_id em PUT /task/{id} retorna HTTP 200 e é silenciosamente ignorado. Para mover de fato uma tarefa e manter seu ID personalizado e histórico, use a interface web do ClickUp (clique com o botão direito -> Move). A associação a múltiplas listas também requer o recurso pago Tasks-in-Multiple-Lists.

Anexos (1)

clickup_upload_attachment - Enviar um arquivo local (captura de tela, PDF) para uma tarefa

Membros do workspace (2)

clickup_get_workspace_members - Todos os membros do workspace
clickup_get_list_members - Membros específicos da lista

Arquitetura

src/
  index.ts          # Entry: McpServer + StdioServerTransport
  client.ts         # ClickUp API v2 fetch wrapper
  types.ts          # Shared Zod schemas + jsonResult helper
  slim.ts           # Response slimming transformers
  tools/
    navigation.ts   # 7 tools
    tasks.ts        # 9 tools (CRUD + custom fields + delete + multi-list)
    tags.ts         # 6 tools
    checklists.ts   # 6 tools
    dependencies.ts # 4 tools
    comments.ts     # 5 tools
    members.ts      # 2 tools
    attachments.ts  # 1 tool (multipart upload)

Licença

MIT