ClickUp

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

Recurso	Este MCP	MCP Oficial do ClickUp
Configuração	Instalação local via npm/npx	MCP remoto (sem instalação)
Autenticação	Somente chave de API	Somente OAuth
Contexto da Tarefa	Completo, com comentários, histórico de status, imagens inline	Requer múltiplas chamadas de ferramentas para contexto completo
Suporte a Imagens	Leitura e escrita: imagens inline com orçamento inteligente de tamanho, e uploads de  automaticamente	Upload via chamadas de ferramentas separadas; base64 limitado a ~200KB
Busca	Busca difusa em tarefas recentes (escopo limitado)	Banco de dados de busca completo do ClickUp
Documentos	Operações CRUD	CRUD + busca em documentos
Controle de Tempo	Visualizar e criar entradas	Temporizadores e entradas
Integração com Chat	Não suportado	Suportado
Apps Conectados	Não suportado	Busca Conectada
Melhor Para	Ferramentas de codificação, automação, coleta de contexto	Apps de chat, gerenciamento de tarefas
Suporte	Comunidade (código aberto)	Oficial do ClickUp

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 arquivo diretamente em vez de usar 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 Busca Conectada
• Você quer suporte oficial e sem instalação local

O Que Você Pode Fazer

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

Codificação Agêntica e Desenvolvimento:

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

Busca 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 vagas de emprego 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?"

Recursos Principais

🔍 Busca Inteligente

• Correspondência difusa em nomes de tarefas, descrições e comentários
• Suporte a busca em vários idiomas para equipes internacionais
• Filtros por responsáveis, projetos, status e metadados

💬 Contexto Completo

• Históricos de comentários e discussões da equipe (até 250 comentários de nível superior), incluindo respostas em threads de comentários
• 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-Anexação: Os campos de descrição nunca são sobrescritos — novo conteúdo é anexado 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 da 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 pode 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

Ferramenta	read-minimal	read	write	Descrição
getTaskById	✅	✅	✅	Obtenha detalhes completos da tarefa, incluindo comentários (com respostas em threads), imagens e metadados
addComment	❌	❌	✅	Adicione comentários a tarefas, ou responda dentro de uma thread de comentários via parent_comment_id
editComment	❌	❌	✅	Corrija seu próprio comentário em até 24h em vez de postar um acompanhamento
updateTask	❌	❌	✅	Atualize tarefas (status, prioridade, responsáveis, etc.); descrições podem ser anexadas ou substituídas inteiramente
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-ANEXAÇÃO para 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 o conteúdo ou nome de páginas existentes com modos de substituição/anexação
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. No instalador da extensão de desktop (.mcpb), a chave de API, ID da equipe, idioma principal, limite de tamanho de upload e janela de edição de comentários são oferecidos como campos de formulário; as variáveis restantes devem ser definidas diretamente no ambiente do servidor.

• CLICKUP_API_KEY: (Obrigatório) Sua chave de API do ClickUp.
• CLICKUP_TEAM_ID: (Obrigatório) Seu ID de Equipe do ClickUp (antigo ID do 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 editComment ainda pode reescrever um comentário. O padrão é 24. Defina como 0 para desativar a edição de comentários inteiramente.
• CLICKUP_PRIMARY_LANGUAGE: (Opcional) Uma dica para o idioma principal usado em suas tarefas do ClickUp (ex.: "de" para alemão, "en" para inglês). Isso ajuda a ferramenta searchTask a fornecer orientação mais personalizada em sua descrição para buscas multilíngues.
• LANG: (Opcional) Se CLICKUP_PRIMARY_LANGUAGE não estiver definido, o MCP verificará esta variável de ambiente padrão (ex.: "en_US.UTF-8", "de_DE") como fallback para inferir o idioma principal.

Orientação de Busca com Consciência de 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 (ex.: alemão), a descrição da ferramenta recomendará especificamente fornecer termos de busca tanto em inglês quanto no idioma detectado (ex.: 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.

Esse 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 continua com o 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 Somente de Anexação (Seguras): 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 um registro de auditoria claro.

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).

Observações:

• 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 etapas de passo a passo como linhas em negrito com a imagem entre elas, como acima.
• Apenas arquivos PNG/JPEG/GIF/WebP reais 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 uma falha de upload posterior é relatada como aviso, pois a tarefa já existe nesse ponto.
• Anexos sempre pertencem a uma tarefa, portanto, páginas de documentos 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