ClickUp

Um servidor MCP para o ClickUp, permitindo que assistentes de IA interajam e gerenciem tarefas em seus espaços de trabalho do ClickUp.

GitHub
23

Documentação

ClickUp MCP Server

smithery badge npm version License: MIT Buy Me A Coffee

Uma implementação de servidor Model Context Protocol para integração com o ClickUp, permitindo que assistentes de IA interajam com espaços de trabalho do ClickUp.

Este servidor é executado via Stdio, conforme a especificação MCP, quando invocado por um cliente MCP.

ClickUp Server MCP server

Início Rápido

Este servidor usa seu ClickUp Personal API Token para autenticação.

  1. Gere um Personal API Token: Nas configurações do seu ClickUp, navegue até "My Settings" > "Apps" e gere um token.
  2. Configure seu cliente MCP (ex.: Claude for Desktop): Defina a variável de ambiente necessária ao configurar o servidor para o seu cliente.

Exemplo de trecho de configuração para um cliente MCP:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["@nazruden/clickup-server"],
      "env": {
        "CLICKUP_PERSONAL_TOKEN": "your_personal_api_token_here"
      }
    }
  }
}
  1. Reinicie seu cliente MCP.

O servidor será baixado e iniciado automaticamente pelo cliente MCP quando necessário.

Instalação via Smithery

Para instalar o ClickUp MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @Nazruden/clickup-mcp-server --client claude

Variáveis de Ambiente

Obrigatórias

  • CLICKUP_PERSONAL_TOKEN: Seu ClickUp Personal API Token. É essencial para que o servidor autentique com a API do ClickUp.

Opcionais

  • LOG_LEVEL: Nível de registro (logging) do servidor. Suporta error, warn, info, debug. O padrão é info.
  • ENCRYPTION_KEY: Uma chave persistente codificada em hexadecimal de 32 bytes. O sistema de configuração (src/config/app.config.ts) carrega ou gera essa chave, e src/security.ts contém funções de criptografia/descriptografia. No entanto, esse mecanismo atualmente não é usado para criptografar o CLICKUP_PERSONAL_TOKEN no fluxo de autenticação do Personal API Token do ClickUpService.
  • PORT: Porta do servidor. Não é usada pelo modo padrão de servidor MCP Stdio, mas pode ser relevante se um transporte HTTP ou recursos HTTP adicionais (como um endpoint separado de health check) forem explicitamente adicionados. O padrão é 3000 na configuração, se lido.

Ferramentas Disponíveis

As seguintes ferramentas MCP estão atualmente implementadas:

Gerenciamento de Tarefas

  • clickup_create_task: Cria uma nova tarefa em uma lista do ClickUp.
    • Requer: list_id, name.
    • Opcional: description, status, priority, assignees, due_date, time_estimate, tags.
  • clickup_update_task: Atualiza as propriedades de uma tarefa existente.
    • Requer: task_id.
    • Opcional: quaisquer propriedades graváveis de ClickUpTask.

Gerenciamento de Equipes e Listas

  • clickup_get_teams: Recupera todas as equipes acessíveis (Workspaces na API v2 do ClickUp).
  • clickup_get_lists: Obtém todas as listas em uma pasta específica.
    • Requer: folder_id.

Gerenciamento de Quadros

  • clickup_create_board: Cria um novo quadro em um espaço do ClickUp.
    • Requer: space_id, name.

Gerenciamento de Espaços

  • clickup_get_spaces: Recupera todos os Espaços de um Workspace (Equipe) específico.
    • Requer: team_id (ID do Workspace).
    • Opcional: archived (booleano, o padrão é false).
  • clickup_create_space: Cria um novo Espaço dentro de um Workspace.
    • Requer: team_id (ID do Workspace), name.
    • Opcional: multiple_assignees (booleano), features (objeto com flags de recursos como due_dates, time_tracking, etc.).
  • clickup_get_space: Recupera detalhes de um Espaço específico.
    • Requer: space_id.
  • clickup_update_space: Atualiza um Espaço existente.
    • Requer: space_id.
    • Opcional: name, color, private, admin_can_manage, archived, features.
  • clickup_delete_space: Exclui um Espaço.
    • Requer: space_id.

Gerenciamento de Pastas

  • clickup_get_folders: Recupera todas as Pastas dentro de um Espaço específico.
    • Requer: space_id.
    • Opcional: archived (booleano, o padrão é false).
  • clickup_create_folder: Cria uma nova Pasta dentro de um Espaço.
    • Requer: space_id, name.
  • clickup_get_folder: Recupera detalhes de uma Pasta específica.
    • Requer: folder_id.
  • clickup_update_folder: Atualiza uma Pasta existente.
    • Requer: folder_id, name.
  • clickup_delete_folder: Exclui uma Pasta.
    • Requer: folder_id.

Gerenciamento de Campos Personalizados

  • clickup_get_custom_fields: Recupera todos os Campos Personalizados acessíveis de uma Lista específica.
    • Requer: list_id.
  • clickup_set_task_custom_field_value: Define o valor de um Campo Personalizado em uma tarefa específica.
    • Requer: task_id, field_id, value.
    • Opcional: value_options (objeto, ex.: { "time": true } para campos de data).
  • clickup_remove_task_custom_field_value: Remove/limpa o valor de um Campo Personalizado de uma tarefa específica.
    • Requer: task_id, field_id.

Gerenciamento de Documentos

Nota: A API do ClickUp para Documentos (especialmente v2, com algumas operações agora usando v3) tem limitações. O conteúdo é tratado principalmente como Markdown. Formatação avançada ou embeds complexos podem não ser totalmente suportados. A exclusão direta de documentos via API não é suportada atualmente pelo endpoint V3 /docs do ClickUp; gerencie o ciclo de vida do Documento por meio de arquivamento ou manipulação de páginas.

  • clickup_search_docs: Pesquisa Documentos dentro de um Workspace (Equipe).
    • Requer: workspace_id.
    • Opcional: query (string), include_archived (booleano).
  • clickup_create_doc: Cria um novo Documento.
    • Requer: workspace_id, name.
    • Opcional: parent (objeto com id e type), visibility (string: "private", "workspace", "public"), create_page (booleano).
  • clickup_get_doc_pages: Recupera a lista de páginas dentro de um Documento específico.
    • Requer: doc_id.
  • clickup_create_doc_page: Cria uma nova página dentro de um Documento específico.
    • Requer: workspace_id, doc_id, name (título da página).
    • Opcional: content (Markdown), orderindex (número, embora a API v3 possa não usá-lo), parent_page_id (string), sub_title (string), content_format (string).
  • clickup_get_doc_page_content: Recupera o conteúdo (Markdown) de uma página específica de Documento.
    • Requer: workspace_id, doc_id, page_id.
    • Opcional: content_format (string).
  • clickup_edit_doc_page_content: Atualiza o conteúdo e/ou título de uma página específica de Documento.
    • Requer: workspace_id, doc_id, page_id, content (Markdown).
    • Opcional: title (string, mapeia para 'name' da API), sub_title (string), content_edit_mode (string: "replace", "append", "prepend"), content_format (string).

Gerenciamento de Visualizações

  • clickup_get_views: Recupera todas as Visualizações de um recurso pai específico (Equipe, Espaço, Pasta ou Lista).
    • Requer: parent_id (ID do recurso pai), parent_type (string: "team", "space", "folder" ou "list").
  • clickup_create_view: Cria uma nova Visualização dentro de uma Equipe, Espaço, Pasta ou Lista.
    • Requer: parent_id, parent_type, name (string: nome da nova Visualização), type (string: tipo da Visualização, ex.: "list", "board", "calendar", "gantt").
    • Opcional: grouping, divide, sorting, filters, columns, team_sidebar, settings (objetos que definem configurações de visualização).
  • clickup_get_view_details: Recupera detalhes de uma Visualização específica.
    • Requer: view_id.
  • clickup_update_view: Atualiza uma Visualização existente.
    • Requer: view_id.
    • Opcional: name (string), grouping, divide, sorting, filters, columns, team_sidebar, settings.
  • clickup_delete_view: Exclui uma Visualização.
    • Requer: view_id.
  • clickup_get_view_tasks: Recupera tarefas pertencentes a uma Visualização específica.
    • Requer: view_id.
    • Opcional: page (número: número da página com índice 0 para paginação).

Desenvolvimento

  1. Clone o repositório:

    git clone <repository_url>
cd clickup-mcp-server

  2. Instale as dependências:

    npm install

  3. Crie um arquivo .env no diretório raiz e adicione seu CLICKUP_PERSONAL_TOKEN:

    CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here
LOG_LEVEL=debug

  4. Inicie em modo de desenvolvimento (Stdio): O servidor escutará mensagens MCP em stdin/stdout.

    npm run dev

    Isso usa ts-node-dev para executar src/index.ts.

  5. Compile para produção:

    npm run build

    Isso compila TypeScript para dist/.

  6. Execute os testes:

    npm test

    Isso executa os testes unitários Jest localizados em src/__tests__. Certifique-se de ter um arquivo .env.test (veja src/__tests__/setup.ts).

Testando com o MCP Inspector

Você pode testar o servidor localmente usando o MCP Inspector:

  1. Certifique-se de que seu CLICKUP_PERSONAL_TOKEN esteja disponível. Você pode:
    • Defini-lo no ambiente do seu shell antes de executar o inspector.
    • Defini-lo na interface do MCP Inspector, se ela oferecer uma opção para variáveis de ambiente do servidor.
    • Tê-lo no seu arquivo local .env (pois src/index.ts carrega dotenv).
  2. Execute o Inspector com o servidor: 
    npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts
    A interface do Inspector deve abrir, permitindo que você se conecte ao servidor e chame suas ferramentas.

Segurança

  • Autentica usando seu ClickUp Personal API Token. Mantenha este token seguro e confidencial. Trate-o como uma senha.
  • O servidor espera que o CLICKUP_PERSONAL_TOKEN seja fornecido via variável de ambiente pelo cliente MCP consumidor ou pelo ambiente de desenvolvimento.
  • O sistema de configuração inclui lógica para um ENCRYPTION_KEY e src/security.ts tem funções de criptografia, mas isso não é aplicado atualmente ao Personal API Token pelo ClickUpService.
  • Nenhum dado sensível (como o próprio token) é registrado por padrão com LOG_LEVEL=info. O nível de debug pode registrar mais detalhes.
  • A limitação de taxa para chamadas à API do ClickUp é tratada registrando as solicitações restantes (veja ClickUpService).

Solução de Problemas

Problemas Comuns

  1. Erros de Autenticação (401 da API do ClickUp)

    • Verifique se a variável de ambiente CLICKUP_PERSONAL_TOKEN está definida corretamente e acessível pelo processo do servidor.
    • Certifique-se de que o token seja válido e não tenha sido revogado nas suas configurações do ClickUp.
    • Verifique os logs do servidor para mensagens de ClickUpService sobre autenticação.

  2. Limitação de Taxa pela API do ClickUp

    • O servidor registra informações de limite de taxa das respostas da API do ClickUp.
    • Se os limites de taxa forem atingidos com frequência, isso indica uso elevado. O servidor em si não implementa filas ou backoff complexo além do que axios possa fazer por padrão.

  3. Servidor Não Iniciando / Problemas de Conexão com o MCP Inspector

    • Certifique-se de que CLICKUP_PERSONAL_TOKEN esteja definido.
    • Se estiver usando npm run dev, verifique erros de TypeScript ou ts-node-dev no console.
    • Se estiver usando o MCP Inspector com node --loader ts-node/esm src/index.ts, certifique-se de que ts-node e as dependências do projeto estejam instalados corretamente.
    • Verifique erros de console de src/index.ts ou ClickUpService.

Obtendo Logs do Servidor

  • Quando executado via npm run dev ou npm start, os logs vão para o console.
  • Se executado por um cliente MCP (como Claude for Desktop), os logs geralmente são gerenciados por esse cliente. Para Claude for Desktop, os logs geralmente podem ser encontrados em:
    • Windows: %USERPROFILE%\AppData\Local\Claude\Logs\mcp\<server_name_and_id>\<process_id>.log (o caminho pode variar ligeiramente)
    • macOS: ~/Library/Logs/Claude/mcp/<server_name_and_id>\<process_id>.log (o caminho pode variar ligeiramente)

Suporte

Se você achar este projeto útil, considere me pagar um café para apoiar o desenvolvimento e a manutenção contínuos.

Buy Me A Coffee

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes

Correção do pipeline de teste