ClickUp

Integre assistentes de IA com o ClickUp para produtividade e gerenciamento de projetos.

GitHub
46

Documentação

ClickUp MCP para Assistentes de IA

Servidor Model Context Protocol (MCP) que permite que assistentes de IA interajam com workspaces do ClickUp. Obtenha contexto completo de tarefas com comentários e imagens, pesquise em projetos, crie e atualize tarefas, colabore por meio de comentários e registre tempo — tudo por meio de linguagem natural.

Este MCP vs. MCP Oficial do ClickUp

Veja também: Documentação Oficial do MCP do ClickUp

RecursoEste MCPMCP Oficial do ClickUp
ConfiguraçãoInstalação local via npm/npxMCP remoto (sem instalação)
AutenticaçãoSomente chave de APISomente OAuth
Contexto da TarefaCompleto, com comentários, histórico de status, imagens inlineRequer múltiplas chamadas de ferramenta para contexto completo
Suporte a ImagensLeitura e escrita: imagens inline com orçamento inteligente de tamanho, e uploads de ![](local/path.png) automaticamenteUpload por chamadas de ferramenta separadas; base64 limitado a ~200KB
PesquisaPesquisa difusa em tarefas recentes (escopo limitado)Banco de dados de pesquisa completo do ClickUp
DocumentosOperações CRUDCRUD + pesquisa de documentos
Controle de TempoVisualizar e criar entradasTemporizadores e entradas
Integração com ChatNão suportadoSuportado
Apps ConectadosNão suportadoPesquisa Conectada
Melhor ParaFerramentas de codificação, automação, coleta de contextoApps de chat, gerenciamento de tarefas
SuporteComunidade (código aberto)ClickUp oficial

Escolha este MCP quando:

  • Você precisa de contexto rico de tarefas com imagens inline para ferramentas de codificação de IA
  • Você quer escrever capturas de tela em tickets por caminho de arquivo local (executando localmente, ele lê o próprio arquivo em vez de receber base64)
  • Você precisa de autenticação por chave de API para automação ou pipelines de CI/CD
  • Você quer o modo read-minimal otimizado para fluxos de trabalho de desenvolvimento

Escolha o MCP Oficial quando:

  • Você precisa de autenticação OAuth para conformidade de segurança empresarial
  • Você precisa de integração com Chat ou recursos de Pesquisa Conectada
  • Você quer suporte oficial e nenhuma instalação local

O Que Você Pode Fazer

Transforme linguagem natural em ações poderosas do ClickUp:

Codificação e Desenvolvimento Agêntico:

  • "Veja CU-abc123, você consegue encontrar o código relevante?"
  • "Você consegue construir o dashboard como descrito em https://app.clickup.com/t/12a23b45c?"
  • "Verifique a tarefa CU-xyz789 e corrija os bugs mencionados nos comentários"
  • "Implemente os endpoints de API descritos na tarefa de integração"

Controle de Tempo e Produtividade:

  • "Reserve 2 horas para a reunião com o cliente no projeto XYZ"
  • "Quanto tempo gastei em tarefas de desenvolvimento esta semana?"
  • "Registre 30 minutos para revisão de código no recurso de autenticação"

Pesquisa Inteligente e Descoberta:

  • "Em qual tarefa mencionei a importação de CSV?"
  • "Encontre todas as tarefas relacionadas à integração do gateway de pagamento"
  • "Mostre-me tarefas em que usuários relataram problemas de login"

Gerenciamento de Fluxo de Trabalho Diário:

  • "O que preciso fazer hoje?"
  • "Crie uma tarefa para corrigir o bug do dashboard na lista de frontend"
  • "Atualize a tarefa de documentação da API para o status 'em revisão'"
  • "Quais tarefas estão bloqueando o lançamento do aplicativo móvel?"

Contexto Rico e Colaboração:

  • "Mostre-me todos os comentários na tarefa de autenticação de usuário"
  • "Qual é a atualização mais recente sobre a migração do banco de dados?"
  • "Adicione um comentário à tarefa de design sobre os novos wireframes"

Gerenciamento de Documentos:

  • "Encontre documentos sobre postagem de vagas no espaço hauptsache.net"
  • "Pesquise documentação de API em todos os espaços"
  • "Leia a documentação da API no espaço de desenvolvimento"
  • "Crie um novo documento de requisitos para o projeto do aplicativo móvel"
  • "Atualize as notas da reunião com as decisões de hoje"
  • "Quais documentos estão no espaço de estratégia de produto?"

Principais Recursos

🔍 Pesquisa Inteligente

  • Correspondência difusa em nomes de tarefas, descrições e comentários
  • Suporte a pesquisa multilíngue para equipes internacionais
  • Filtre por responsáveis, projetos, status e metadados

💬 Contexto Completo

  • Históricos completos de comentários e discussões da equipe
  • Descrições de tarefas com imagens incorporadas
  • Descrições de listas e diretrizes de projeto
  • Conteúdo de documentos com navegação de páginas
  • Acesso ao histórico completo de tarefas e decisões

⏱️ Controle de Tempo

  • Registre entradas de tempo com descrições
  • Visualize registros e entradas de tempo históricos
  • Consulte entradas de tempo por tarefa ou intervalo de datas

📋 Gerenciamento de Tarefas e Documentos

  • Crie e atualize tarefas com descrições em markdown
  • Crie, leia e atualize documentos e páginas
  • Adicione comentários e colabore com membros da equipe
  • Gerencie prioridades, datas de vencimento, responsáveis e tags
  • Lide com estimativas de tempo e valores de campos personalizados

🔒 Recursos de Segurança

  • Descrições Somente-Acrescentar: Os campos de descrição nunca são sobrescritos — novo conteúdo é acrescentado com segurança com carimbos de data/hora
  • Atualizações Normais de Campos: Status, prioridade, responsáveis, tags e datas podem ser atualizados normalmente (facilmente reversíveis pelo histórico do ClickUp)

Instalação

Pré-requisitos

Para todos os métodos de instalação, você precisará de:

  • Sua CLICKUP_API_KEY (Ícone de Perfil > Configurações > Apps > Token de API ~ geralmente começa com pk_)
  • Seu CLICKUP_TEAM_ID (O número de 7 a 10 dígitos na URL quando você está nas configurações)

Opção 1: Pacote MCPB (Recomendado para Claude Desktop)

Baixe o pacote pré-compilado em nossa página de releases. Este método não requer instalação do Node.js.

Você verá uma tela de configuração onde será solicitado a inserir sua chave de API e ID da equipe.

Opção 2: Instalação via NPX

Este método atualiza automaticamente para a versão mais recente e é preferido para usuários que desejam os recursos mais novos.

Para Claude Desktop, Windsurf, Cursor e outros:

Adicione o seguinte ao seu arquivo de configuração MCP:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": [
        "@hauptsache.net/clickup-mcp@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id"
      }
    }
  }
}

Substitua your_api_key e your_team_id pelas suas credenciais reais do ClickUp.

Onde adicionar esta configuração:

  • Claude Desktop: Configurações > Desenvolvedor > Editar Config
  • Windsurf: Adicione ao seu arquivo de configuração MCP
  • Cursor: Configure pelo painel de configurações do MCP

Opção 3: Integração com Ferramentas de Codificação

Claude Code (CLI):

claude mcp add --scope user clickup \
  --env CLICKUP_API_KEY=YOUR_KEY \
  --env CLICKUP_TEAM_ID=YOUR_ID \
  --env CLICKUP_MCP_MODE=read-minimal \
  --env MAX_IMAGES=16 \
  --env MAX_RESPONSE_SIZE_MB=4 \
  -- npx -y @hauptsache.net/clickup-mcp

O Claude Code consegue lidar com muitas imagens, portanto os limites aumentados são recomendados.

Observe o CLICKUP_MCP_MODE=read-minimal. Esta é minha recomendação de uso, mas sinta-se à vontade para usar um dos outros modos.

OpenAI Codex: Adicione estas linhas ao seu arquivo ~/.codex/config.toml:

[mcp_servers.clickup]
command = "npx"
args = ["-y", "@hauptsache.net/clickup-mcp@latest"]
env = { "CLICKUP_API_KEY" = "YOUR_KEY", "CLICKUP_TEAM_ID" = "YOUR_ID", "CLICKUP_MCP_MODE" = "read-minimal" }

O Codex parece não conseguir lidar com imagens de MCPs. Veja este problema para mais detalhes.

Observe o CLICKUP_MCP_MODE=read-minimal. Esta é minha recomendação de uso, mas sinta-se à vontade para usar um dos outros modos.

Modos MCP e Ferramentas Disponíveis

O ClickUp MCP suporta três modos operacionais para equilibrar funcionalidade, segurança e desempenho:

  • 🚀 read-minimal: Perfeito para assistentes de codificação de IA e coleta de contexto
  • 📖 read: Acesso somente leitura completo para exploração de projetos e compreensão de fluxos de trabalho
  • ✏️ write (Padrão): Funcionalidade completa para gerenciamento de tarefas e fluxos de produtividade
Ferramentaread-minimalreadwriteDescrição
getTaskById✅✅✅Obtenha detalhes completos da tarefa, incluindo comentários, imagens e metadados
addComment❌❌✅Adicione comentários a tarefas para colaboração
editComment❌❌✅Corrija seu próprio comentário em até 24h em vez de postar um acompanhamento
updateTask❌❌✅Atualize tarefas (status, prioridade, responsáveis, etc.) com descrições SEGURAS SOMENTE-ACRESCENTAR
createTask❌❌✅Crie novas tarefas com suporte completo a markdown
searchTasks✅✅✅Encontre tarefas por conteúdo, palavras-chave, responsáveis ou contexto de projeto
searchSpaces❌✅✅Navegue pela estrutura do workspace, organização de projetos e documentos
getListInfo❌✅✅Obtenha detalhes da lista e status disponíveis para criação de tarefas
updateListInfo❌❌✅Atualizações SEGURAS SOMENTE-ACRESCENTAR em descrições de listas (preserva o conteúdo existente)
getTimeEntries❌✅✅Visualize entradas de tempo e analise o tempo gasto entre projetos
createTimeEntry❌❌✅Registre entradas de tempo para acompanhamento de tarefas
readDocument❌✅✅Obtenha detalhes de documentos, estrutura de páginas e conteúdo com navegação
searchDocuments❌✅✅Pesquise documentos por nome e espaço com correspondência difusa e filtragem por espaço
updateDocumentPage❌❌✅Atualize conteúdo ou nome de páginas existentes com modos de substituição/acréscimo
createDocumentOrPage❌❌✅Crie novos documentos com primeira página, ou adicione páginas/subpáginas a documentos existentes

Definindo o Modo

Adicione o modo à sua configuração MCP:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "@hauptsache.net/clickup-mcp@latest"],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id",
        "CLICKUP_MCP_MODE": "read"
      }
    }
  }
}

Configuração

Este servidor MCP pode ser configurado usando variáveis de ambiente:

  • CLICKUP_API_KEY: (Obrigatório) Sua chave de API do ClickUp.
  • CLICKUP_TEAM_ID: (Obrigatório) Seu ID de Equipe do ClickUp (antigo ID de Workspace).
  • CLICKUP_MCP_MODE: (Opcional) Controla quais ferramentas estão disponíveis. Opções: read-minimal, read, write (padrão).
  • MAX_IMAGES: (Opcional) O número máximo de imagens a retornar para uma tarefa em getTaskById. O padrão é 4.
  • MAX_RESPONSE_SIZE_MB: (Opcional) O tamanho máximo de resposta em megabytes para getTaskById. Usa orçamento inteligente de tamanho para caber as imagens mais importantes dentro do limite. O padrão é 1.
  • MAX_UPLOAD_SIZE_MB: (Opcional) O tamanho máximo de uma única imagem enviada ao escrever comentários ou descrições. O padrão é 10.
  • CLICKUP_COMMENT_EDIT_WINDOW_HOURS: (Opcional) Por quanto tempo após a criação o editComment pode reescrever um comentário. O padrão é 24. Defina como 0 para desativar completamente a edição de comentários.
  • CLICKUP_PRIMARY_LANGUAGE: (Opcional) Uma dica para o idioma principal usado em suas tarefas do ClickUp (por exemplo, "de" para alemão, "en" para inglês). Isso ajuda a ferramenta searchTask a fornecer orientação mais personalizada em sua descrição para pesquisas multilíngues.
  • LANG: (Opcional) Se CLICKUP_PRIMARY_LANGUAGE não estiver definido, o MCP verificará esta variável de ambiente padrão (por exemplo, "en_US.UTF-8", "de_DE") como fallback para inferir o idioma principal.

Orientação de Pesquisa Ciente do Idioma

A descrição da ferramenta searchTask será ajustada dinamicamente com base no idioma principal detectado:

  • Se CLICKUP_PRIMARY_LANGUAGE ou LANG sugerir um idioma principal conhecido (por exemplo, alemão), a descrição da ferramenta recomendará especificamente fornecer termos de busca tanto em inglês quanto no idioma detectado (por exemplo, alemão) para obter resultados ideais.
  • Se nenhum idioma principal for detectado, uma recomendação mais geral para espaços de trabalho multilíngues será fornecida.

Este recurso visa melhorar a eficácia da busca quando o idioma das consultas do usuário (geralmente inglês) difere do idioma das tarefas no ClickUp, sem fazer com que o próprio MCP realize traduções. A responsabilidade de fornecer termos de busca bilíngues ainda cabe ao agente que chama o MCP, mas o MCP oferece conselhos mais específicos se tiver uma dica de idioma.

Suporte a Formatação Markdown

Descrições de tarefas e documentação de listas suportam formatação markdown completa:

Exemplos

Criação de Tarefa com Markdown:

Create a task called "API Integration" with description:
# API Integration Requirements

## Authentication
- Implement OAuth 2.0 flow
- Add JWT token validation
- **Priority**: High security standards

## Endpoints
1. `/api/users` - User management
2. `/api/data` - Data retrieval
3. `/api/webhook` - Event notifications

## Testing
- [ ] Unit tests for auth flow
- [ ] Integration tests
- [ ] Load testing with 1000+ concurrent users

> **Note**: This replaces the legacy REST implementation

See related task: https://app.clickup.com/t/abc123

Atualizações Apenas com Anexação (Seguro): Ao atualizar descrições de tarefas, o conteúdo é anexado com segurança:

[Existing task description content]

---
**Edit (2024-01-15):** Added new acceptance criteria based on client feedback:
- Must support mobile responsive design
- Performance requirement: < 2s load time

Isso garante que nenhum conteúdo existente seja perdido, mantendo uma trilha de auditoria clara.

Escrevendo Imagens em Tickets

addComment, editComment, createTask e updateTask aceitam imagens como markdown comum. Como este servidor roda localmente, ele lê o arquivo por conta própria - portanto, um caminho local é suficiente:

Ist umgesetzt. So sieht es aus:

**1. Login öffnen** – der Kunde gibt nur seine E-Mail-Adresse ein.

![Die Login-Maske fragt nur nach der E-Mail](/Users/me/shots/login.png)

Fontes aceitas: caminhos de arquivo locais, URIs data:, URLs http(s) (baixadas e depois reenviadas) e URLs de anexos existentes do ClickUp (incorporadas sem reenvio).

Notas:

  • Prefira caminhos em vez de base64. Um caminho custa alguns tokens; a mesma captura de tela como uma URI data: custa aproximadamente 4/3 do tamanho do arquivo na solicitação.
  • A legenda se torna o nome do arquivo do anexo, e esse nome é o que o ClickUp exibe abaixo da imagem - portanto, escreva uma legenda que leia bem.
  • Uma imagem dentro de uma lista numerada quebra a numeração do ClickUp. Escreva as etapas do passo a passo como linhas em negrito com a imagem entre elas, como acima.
  • Apenas arquivos reais PNG/JPEG/GIF/WebP são enviados - o conteúdo é verificado, não a extensão. Um arquivo que falha aborta a escrita: addComment, editComment e updateTask relatam cada referência quebrada e não alteram nada, para que o markdown possa ser corrigido e a chamada repetida sem criar duplicatas. createTask valida suas imagens antes de criar a tarefa; apenas um upload que falha posteriormente é relatado como um aviso, pois a tarefa já existe nesse ponto.
  • Anexos sempre pertencem a uma tarefa, portanto, páginas de documento não podem incorporar uploads dessa forma.

Desempenho e Limitações

Otimizado para Fluxos de Trabalho de IA:

  • Processamento Inteligente de Imagens: Orçamento inteligente de tamanho prioriza as imagens mais recentes, respeitando tanto os limites de contagem (MAX_IMAGES, padrão: 4) quanto os limites de tamanho total da resposta (MAX_RESPONSE_SIZE_MB, padrão: 1MB)
  • Escopo de Busca: Busca nas 1000-3000 tarefas mais recentes para evitar atingir limites de taxa (o número exato varia por endpoint)
  • Resultados de Busca: Retorna até 50 correspondências mais relevantes para evitar sobrecarregar o agente com muitos resultados

Escopo Atual:

  • Focado em operações no nível de tarefa, em vez de gerenciamento em massa do espaço de trabalho
  • Otimizado para fluxos de trabalho conversacionais de IA, em vez de migração de dados
  • Projetado para aumento de produtividade, não para operações administrativas

Essas limitações garantem desempenho confiável, cobrindo os casos de uso mais comuns tanto para contexto de desenvolvimento quanto para gerenciamento de produtividade.

Licença

MIT