ClickUp

Interaja com a API de gerenciamento de tarefas do ClickUp para gerenciar projetos e tarefas por meio de linguagem natural.

GitHub

Documentação

Servidor MCP ClickUp

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA interajam com a API de gerenciamento de tarefas do ClickUp. Este servidor fornece recursos abrangentes de gerenciamento de tarefas por meio de linguagem natural, com foco em fluxos de trabalho essenciais de projetos, em vez do conjunto completo de recursos do ClickUp.

Desenvolvido pela equipe da Diversio para um gerenciamento de tarefas simplificado com IA.

🚀 O Que Este Servidor Oferece

✅ Gerenciamento Essencial de Tarefas

Operações CRUD de Tarefas - Criar, ler, atualizar e excluir tarefas
Organização de Tarefas - Navegar por espaços, pastas e listas
Busca e Filtragem de Tarefas - Encontrar tarefas por vários critérios
Comentários e Colaboração - Ler e criar comentários em tarefas
Gerenciamento de Usuários e Atribuições - Listar usuários, encontrar por nome/e-mail, atribuir a tarefas
Gerenciamento de Status - Atualizar e acompanhar status de tarefas

✅ Recursos de Produtividade

Operações em Lote - Atualizar ou mover várias tarefas de uma vez
Controle de Tempo - Registrar horas e visualizar horas acompanhadas
Modelos de Tarefas - Criar tarefas a partir de modelos predefinidos (relatório de bug, solicitação de recurso, revisão de código)
Cadeias de Tarefas - Criar sequências de tarefas dependentes
Análises da Equipe - Visualizar distribuição de carga de trabalho e métricas de conclusão

✅ Suporte Flexível a IDs

IDs padrão do ClickUp (abc123)
Padrões de ID personalizados (gh-123, bug-456)
URLs do ClickUp (https://app.clickup.com/t/abc123)
Formato hash (#123)

❌ O Que NÃO Está Incluído

Este servidor foca no essencial do gerenciamento de tarefas. Não suportado:

Documentos do ClickUp
Quadros brancos
Painéis
Automações/Fluxos de trabalho
Metas/Objetivos
Gerenciamento de arquivos/anexos
Gerenciamento de webhooks
Operações avançadas de campos personalizados
Visualizações de calendário
Integração de formulários

Cobertura da API: ~30-40% da API completa do ClickUp, cobrindo os fluxos de trabalho de gerenciamento de tarefas mais comuns.

Instalação

Início Rápido (Recomendado)

# Install from GitHub (latest)
uvx --from git+https://github.com/DiversioTeam/clickup-mcp clickup-mcp

# Or from PyPI (when published)
uvx clickup-mcp

Instalação para Desenvolvimento

git clone https://github.com/DiversioTeam/clickup-mcp
cd clickup-mcp
uv sync
uv run clickup-mcp

Configuração

Configuração da Chave de API

# Set your ClickUp API key
uvx clickup-mcp set-api-key YOUR_API_KEY_HERE

# Or set environment variable
export CLICKUP_MCP_API_KEY=your_api_key

Como Obter Sua Chave de API do ClickUp

Instruções passo a passo:

Faça login no ClickUp em https://app.clickup.com
Navegue até Configurações:
- Clique no seu avatar/foto de perfil no canto inferior esquerdo
- Selecione "Configurações" no menu suspenso
Vá para a seção Apps:
- Na barra lateral esquerda, clique em "Apps"
- Depois clique em "API" (ou acesse diretamente https://app.clickup.com/settings/apps)
Gere o Token da API:
- Clique no botão "Gerar" para criar um novo token de API pessoal
- Importante: Este token será exibido apenas uma vez!
Copie e Salve:
- Copie o token gerado imediatamente
- Armazene-o com segurança (gerenciador de senhas recomendado)
- Configure-o usando: uvx clickup-mcp set-api-key YOUR_TOKEN_HERE

Notas Importantes:

Tokens de API pessoais têm as mesmas permissões da sua conta de usuário
Mantenha seu token seguro - trate-o como uma senha
Se você perder o token, precisará gerar um novo
Os tokens não expiram, mas podem ser revogados na mesma página de configurações

Uso com Assistentes de IA

Claude Code (CLI)

Adicione ao ~/.config/claude-code/mcp-settings.json:

{
  "servers": {
    "clickup": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
    }
  }
}

Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "clickup": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
    }
  }
}

VS Code

O VS Code tem excelente suporte a MCP por meio de integração nativa e extensões. Várias opções de configuração disponíveis:

Opção 1: MCP Nativo do VS Code (Recomendado)

O VS Code agora tem suporte integrado a MCP com GitHub Copilot e Modo Agente. Adicione ao seu workspace:

Crie .vscode/mcp.json no seu projeto:

{
  "servers": {
    "clickup": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
    }
  }
}

Ou adicione às Configurações do Usuário do VS Code:

Abra a Paleta de Comandos (Ctrl+Shift+P / Cmd+Shift+P)
Execute "Preferências: Abrir Configurações do Usuário (JSON)"
Adicione às configurações:

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "uvx",
        "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
      }
    }
  }
}

Opção 2: Extensões do VS Code com Suporte a MCP

Extensão Copilot MCP:

Instale "Copilot MCP" do Marketplace do VS Code
Pesquise, gerencie e instale servidores MCP diretamente do VS Code
A extensão ajudará você a configurar o servidor MCP do ClickUp

Cline (Assistente de Codificação com IA):

Instale a extensão "Cline" para codificação avançada com IA e suporte a MCP
Configure o servidor MCP do ClickUp por meio das configurações do Cline

Gerenciando Servidores MCP no VS Code

Abra a Paleta de Comandos (Ctrl+Shift+P / Cmd+Shift+P)
Execute "MCP: Listar Servidores" para visualizar os servidores configurados
Selecione o servidor ClickUp para Iniciar/Parar/Reiniciar ou visualizar logs
Use "MCP: Mostrar Saída" para depuração

Verifique a Configuração do VS Code

Certifique-se de que sua chave de API do ClickUp está configurada: uvx clickup-mcp set-api-key YOUR_KEY
No VS Code, pergunte ao GitHub Copilot: "Você pode listar meus espaços do ClickUp usando ferramentas MCP?"
Verifique o status do servidor MCP com a Paleta de Comandos → "MCP: Listar Servidores"

Ferramentas Disponíveis (28 Ferramentas)

📝 Gerenciamento de Tarefas

create_task - Criar novas tarefas
get_task - Obter detalhes da tarefa (suporta vários formatos de ID)
update_task - Atualizar propriedades da tarefa
delete_task - Excluir tarefas
create_task_from_template - Criar a partir de modelos predefinidos
create_task_chain - Criar sequências de tarefas dependentes

🔍 Descoberta de Tarefas

list_tasks - Listar tarefas com opções de filtragem
search_tasks - Buscar tarefas por texto e critérios
get_subtasks - Obter todas as subtarefas de uma tarefa pai
get_task_comments - Obter comentários em tarefas
create_task_comment - Criar comentários em tarefas

👥 Atribuição e Status

get_task_status - Obter status atual da tarefa
update_task_status - Alterar status da tarefa
get_assignees - Listar responsáveis pela tarefa
assign_task - Atribuir usuários a tarefas

🗂️ Navegação

list_spaces - Listar todos os espaços no workspace
list_folders - Listar pastas em um espaço
list_lists - Listar todas as listas
find_list_by_name - Encontrar listas por nome

⚡ Operações em Lote

bulk_update_tasks - Atualizar várias tarefas de uma vez
bulk_move_tasks - Mover várias tarefas para listas diferentes

⏱️ Controle de Tempo

get_time_tracked - Obter tempo registrado para usuários/períodos
log_time - Registrar tempo gasto em tarefas

📊 Análises

get_team_workload - Ver distribuição de tarefas entre membros da equipe
get_task_analytics - Obter métricas de velocidade e taxas de conclusão

👤 Gerenciamento de Usuários

list_users - Listar todos os usuários no workspace
get_current_user - Obter detalhes do usuário autenticado atual
find_user_by_name - Encontrar usuários por nome ou e-mail

Exemplos de Uso

Comandos em Linguagem Natural

Pergunte ao seu assistente de IA:

"Create a bug report for login issues in the Development list"
"Show me all high-priority tasks assigned to me"
"Move all completed tasks from Sprint 1 to Archive"
"Log 2 hours on task gh-123 for debugging"
"What's our team's current workload?"
"Create a task chain: Design → Implement → Test → Deploy"
"Add a comment to task GH-3761 saying 'testing complete'"
"Get all comments on the bug report task"
"Comment on task abc123 and assign it to John"

Modelos de Tarefas

"Create a bug report template for the payment processing issue"
"Use the code review template for PR #456"
"Create a feature request for dark mode"

Consultas de Análises

"What's our task completion rate this month?"
"Who has the most tasks assigned?"
"Show me time tracked on the API project"

Desenvolvimento

Executando Testes

# Run all tests (62 tests)
uv run pytest

# Run with coverage
uv run pytest --cov=clickup_mcp

# Run specific test
uv run pytest tests/test_client.py::test_create_task

Qualidade do Código

# Check code style
uv run ruff check .

# Format code
uv run ruff format .

# Type checking
uv run mypy src/

Solução de Problemas

Verificar Configuração

# Verify API key is configured
uv run clickup-mcp check-config

# Test API connection
uv run clickup-mcp test-connection

Modo de Depuração

# Run with debug logging
uv run clickup-mcp --debug

Testes Locais com Claude Code

# Add the server for local testing with Claude Code CLI
claude mcp add clickup-local -- uv run clickup-mcp

# Then you can test the functionality immediately
# Example: List spaces, create tasks, add comments, etc.

Limitações Técnicas

Limite de Taxa: Sem limite de taxa integrado (ClickUp: 100 req/min)
Paginação: Suporte limitado a paginação
Cache: Nenhum cache de resposta implementado
Campos Personalizados: Modelos existem, mas com suporte limitado de ferramentas
Recuperação de Erros: Tratamento básico de erros sem nova tentativa sofisticada

Contribuindo

Aceitamos contribuições! Áreas de foco:

Melhorias Prioritárias

Tratamento aprimorado de erros e lógica de nova tentativa
Implementação de cache de respostas
Melhor suporte a paginação
Suporte expandido a campos personalizados

Como Contribuir

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/improvement)
Faça alterações e adicione testes
Certifique-se de que todos os testes passem (uv run pytest)
Execute o linting (uv run ruff check .)
Envie um Pull Request

Configuração de Desenvolvimento

git clone https://github.com/yourusername/clickup-mcp
cd clickup-mcp
uv sync
uv run pytest  # Ensure tests pass

Suporte

Problemas: GitHub Issues
Discussões: GitHub Discussions
E-mail: tech@diversio.com

Licença

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

Agradecimentos

Desenvolvido pela equipe da Diversio
Desenvolvido com Model Context Protocol
Usa ClickUp API v2