@rafadepaula/clickup-mcp

Servidor Model Context Protocol (MCP) completo para o ClickUp em Node.js / TypeScript com suporte a todas as 61 ferramentas oficiais, utilizando conexão direta à API REST do ClickUp com limites de requisição altos.

⚡ Por que este MCP?

O servidor MCP oficial hospedado pela ClickUp (https://mcp.clickup.com/mcp) impõe um limite muito baixo de apenas 100 chamadas diárias no plano gratuito:

⚡ Daily MCP limit reached (100/100 calls used). Try again in 14h.

Este servidor conecta-se diretamente à API REST oficial do ClickUp (v2 e v3) usando seu Personal API Token (pk_...), oferecendo o limite padrão da API pública de 100+ requisições por minuto (mais de 140.000 requisições por dia!).

🚀 Como Usar com npx

Você pode executar o servidor diretamente via npx sem precisar clonar o repositório manualmente:

# Comando direto (shorthand do GitHub):
npx rafadepaula/clickup-mcp

# Ou especificando explicitamente github:
npx github:rafadepaula/clickup-mcp

# Ou via pacote npm (quando publicado no registry):
npx @rafadepaula/clickup-mcp

Configuração no seu cliente MCP (Claude Desktop, Cursor, Antigravity, etc.)

Adicione ao seu arquivo de configuração MCP (claude_desktop_config.json, mcp_config.json, etc.):

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": [
        "-y",
        "github:rafadepaula/clickup-mcp"
      ],
      "env": {
        "CLICKUP_API_TOKEN": "pk_seu_token_aqui"
      }
    }
  }
}

Configuração mínima de 1 variável: Basta fornecer CLICKUP_API_TOKEN! O servidor descobre automaticamente seu Workspace (team_id), membros e tipos de tarefas.

🛠️ Catálogo Completo das 61 Ferramentas

O servidor implementa exatamente as mesmas 61 tools do MCP do ClickUp:

1. Gestão de Tarefas (Tasks)

• clickup_create_task - Cria tarefas completas (suporte a Markdown, prioridade, prazos, estimativas, campos customizados e subtarefas).
• clickup_get_task - Retorna detalhes da tarefa e subtarefas.
• clickup_update_task - Atualiza propriedades, status, responsáveis, prioridade e campos customizados.
• clickup_delete_task - Remove uma tarefa.
• clickup_filter_tasks - Filtra tarefas por lista, espaço, pasta, tags, status, datas e responsáveis.
• clickup_search - Busca inteligente por palavras-chave em tarefas e conteúdos do workspace.
• clickup_move_task - Move tarefa para uma nova lista principal.
• clickup_merge_tasks - Mescla tarefas de origem em uma tarefa de destino.

2. Relacionamentos, Tags e Dependências

• clickup_add_tag_to_task / clickup_remove_tag_from_task - Adiciona e remove tags da tarefa.
• clickup_add_task_dependency / clickup_remove_task_dependency - Gerencia dependências (waiting_on e blocking).
• clickup_add_task_link / clickup_remove_task_link - Cria e remove links entre tarefas.
• clickup_add_task_to_list / clickup_remove_task_from_list - Adiciona e remove tarefas de listas secundárias.

3. Listas e Pastas (Lists & Folders)

• clickup_create_folder / clickup_get_folder / clickup_update_folder - Gerenciamento de pastas.
• clickup_create_list / clickup_create_list_in_folder / clickup_get_list / clickup_update_list - Gerenciamento de listas.

4. Hierarquia e Membros

• clickup_get_workspace_hierarchy - Visualiza árvore completa de espaços, pastas e listas.
• clickup_get_workspace_members - Lista membros do workspace.
• clickup_find_member_by_name - Localiza membro por nome ou e-mail.
• clickup_resolve_assignees - Converte nomes, e-mails ou "me" em IDs numéricos de usuário.
• clickup_get_custom_fields - Consulta campos customizados por lista, pasta, espaço ou workspace.

5. Comentários (Comments)

• clickup_create_task_comment - Adiciona comentário a uma tarefa.
• clickup_get_task_comments - Lista comentários da tarefa.
• clickup_create_comment - Cria comentário em tarefa, lista ou view.
• clickup_update_comment - Edita texto ou resolve comentário.
• clickup_delete_comment - Exclui comentário.
• clickup_get_threaded_comments - Retorna respostas aninhadas (threads).

6. Anexos e Arquivos (Attachments)

• clickup_attach_task_file - Anexa arquivo à tarefa via Base64 ou URL da web.
• clickup_request_attachment_upload - Gera parâmetros para upload multipart de arquivos locais.
• clickup_download_task_attachment - Obtém metadados e URL de download de anexo.
• clickup_list_document_page_attachments / clickup_download_document_page_attachment

7. Documentos (Docs v3)

• clickup_create_document - Cria documento no espaço, pasta ou lista.
• clickup_list_document_pages - Lista estrutura de páginas do documento.
• clickup_get_document_pages - Obtém conteúdo em Markdown das páginas.
• clickup_create_document_page - Cria nova página no documento.
• clickup_update_document_page - Atualiza título e conteúdo da página (replace, append, prepend).

8. Chat

• clickup_get_chat_channels - Lista canais de chat do workspace.
• clickup_send_chat_message - Envia mensagem ou resposta para um canal.
• clickup_get_chat_channel_messages - Obtém mensagens do canal.
• clickup_get_chat_message_replies - Obtém respostas aninhadas de uma mensagem.

9. Lembretes (Reminders)

• clickup_create_reminder - Cria lembrete pessoal com data/hora.
• clickup_search_reminders - Busca lembretes.
• clickup_update_reminder - Atualiza ou conclui lembrete.

10. Controle de Tempo (Time Tracking)

• clickup_start_time_tracking - Inicia cronômetro em uma tarefa.
• clickup_stop_time_tracking - Para o cronômetro ativo.
• clickup_add_time_entry - Registra entrada manual de tempo.
• clickup_get_current_time_entry - Consulta cronômetro em execução.
• clickup_get_time_entries - Consulta histórico de tempo registrado.
• clickup_get_task_time_in_status / clickup_get_bulk_tasks_time_in_status - Tempo por status.

11. Compatibilidade Geral

• clickup_get_operators
• clickup_execute_operator
• clickup_get_schema

💻 Desenvolvimento Local

# Instalar dependências
npm install

# Compilar TypeScript
npm run build

# Executar bateria completa de testes de integração contra a API
npm test

# Testar via protocolo padrão MCP stdio
npx tsx src/test/test-mcp-protocol.ts

📄 Licença

MIT © Rafael de Paula