ClickUp集成服务器

MCP Server ClickUp v2.5.0

Servidor MCP para integração do ClickUp com Claude Desktop e outros clientes MCP.

Status do Projeto

Documentação

• PRD completo - Requisitos e decisões técnicas
• Detalhamento das Sprints - O que fazer em cada sprint

Instalação

# Clonar/copiar o projeto
cd "C:\Users\Claudio Camozzi\vscode\mcp server clickup"

# Instalar dependências
pip install -e .

Configuração

Criar arquivo .env:

CLICKUP_API_TOKEN=seu_token_aqui

Uso com Claude Desktop

Adicionar ao claude_desktop_config.json:

{
  "mcpServers": {
    "clickup": {
      "command": "python",
      "args": ["C:\\Users\\Claudio Camozzi\\vscode\\mcp server clickup\\src\\clickup_mcp.py"],
      "env": {
        "CLICKUP_API_TOKEN": "seu_token"
      }
    }
  }
}

Tools Disponíveis

Tools Atuais (v2.5 - 58 tools)

Estas tools já estão implementadas e funcionando:

Modos de Output (v2.0 - Implementado)

Todas as tools de listagem suportam 3 modos de output:

# COMPACT (default) - 1 linha por item - RESOLVE TRAVAMENTO
output_mode="compact"

# DETAILED - formato completo (~12 linhas por item)
output_mode="detailed"

# JSON - raw JSON para processamento
output_mode="json"

Resiliência (v2.1)

O servidor implementa:

• Retry automático: 3 tentativas com backoff exponencial para erros transientes
• Cache TTL: 5 min para estrutura (spaces, folders), 1 min para tasks
• Rate limiting: 100 requests/minuto para respeitar limites do ClickUp
• Connection pooling: Reutilização de conexões HTTP

Configurável via variáveis de ambiente:

DEFAULT_TIMEOUT=30.0
CACHE_TTL_STRUCTURE=300
CACHE_TTL_TASKS=60
LOG_LEVEL=INFO

Qualidade (v2.2)

• Correlation ID: Rastreamento de requests com ID único de 8 caracteres
• Métricas: Contadores de chamadas, cache hit rate, retries
• Logging estruturado: loguru com correlation ID em cada log
• 275 testes: Cobertura completa de formatação, cache, métricas, correlation ID, retry, rate limiting, timeout, e tools MCP com mocks HTTP (96% cobertura)

Nova tool: clickup_get_metrics - retorna métricas de diagnóstico do servidor.

Sprint 5 - Diferencial (v2.3)

Novas features que diferenciam este MCP:

Modo Read-Only

Segurança para ambientes de produção. Configure via variável de ambiente:

READ_ONLY_MODE=true

Quando ativo, todas as operações de escrita (create, update, delete) são bloqueadas.

Busca Fuzzy

Nova tool clickup_fuzzy_search_tasks para busca aproximada:

# Encontra tasks mesmo com erros de digitação
clickup_fuzzy_search_tasks(
    list_id="123",
    query="relatorio",      # encontra "Relatório Mensal"
    threshold=0.5           # 0.0-1.0, maior = mais preciso
)

Time Tracking+

Novas tools para horas faturáveis:

• clickup_create_time_entry - Criar registro com flag billable
• clickup_get_billable_report - Relatório de horas faturáveis por período

Custom Fields (v2.4)

Suporte completo para manipular valores de custom fields:

Tools

• clickup_get_custom_fields - Lista campos disponíveis (obter IDs)
• clickup_set_custom_field_value - Define valor de um campo em uma task
• clickup_remove_custom_field_value - Remove valor de um campo
• clickup_create_task - Agora aceita custom_fields na criação

Exemplos de Uso

# Listar custom fields disponíveis
clickup_get_custom_fields(list_id="123")

# Definir valor de texto
clickup_set_custom_field_value(
    task_id="abc123",
    field_id="field_xyz",
    value="Meu texto"
)

# Definir dropdown (usar ID da opção)
clickup_set_custom_field_value(
    task_id="abc123",
    field_id="dropdown_field",
    value="option_id_aqui"
)

# Criar task com custom fields
clickup_create_task(
    list_id="123",
    name="Nova Task",
    custom_fields=[
        {"id": "field1", "value": "Texto"},
        {"id": "field2", "value": 100},
        {"id": "field3", "value": True}
    ]
)

Formatos de Valor por Tipo

Sprint 7 - API Completa (v2.5)

Tags

# Listar tags do space
clickup_get_space_tags(space_id="space123")

# Criar tag
clickup_create_space_tag(space_id="space123", name="urgente", bg_color="#ff0000")

# Adicionar tag à task
clickup_add_tag_to_task(task_id="task123", tag_name="urgente")

# Remover tag da task
clickup_remove_tag_from_task(task_id="task123", tag_name="urgente")

Dependencies

# Adicionar dependência (task A espera task B)
clickup_add_dependency(
    task_id="taskA",
    depends_on="taskB"  # A espera B terminar
)

# Link bidirecional entre tasks
clickup_add_task_link(task_id="task1", links_to="task2")

Checklists CRUD

# Criar checklist
clickup_create_checklist(task_id="task123", name="Itens para Revisar")

# Adicionar item
clickup_create_checklist_item(
    checklist_id="checklist123",
    name="Revisar documentação",
    assignee="user_id"  # opcional
)

# Marcar como resolvido
clickup_update_checklist_item(
    checklist_id="checklist123",
    item_id="item456",
    resolved=True
)

Timer

# Iniciar timer na task
clickup_start_timer(team_id="team123", task_id="task456", billable=True)

# Verificar timer em execução
clickup_get_running_timer(team_id="team123")

# Parar timer
clickup_stop_timer(team_id="team123")

Templates

# Listar templates disponíveis
clickup_get_task_templates(team_id="team123")

# Criar task a partir de template
clickup_create_task_from_template(
    list_id="list123",
    template_id="tpl456",
    name="Nova Task do Template"
)

Refinamentos v2.3.1 (Nota 9+)

Melhorias para atingir excelência em todos os aspectos:

Performance

• rapidfuzz: Busca fuzzy otimizada com SIMD (O(n) vs O(n*m) do Levenshtein)

Arquitetura

• Exceções específicas: ClickUpError, ConfigurationError, ClickUpAPIError, RateLimitError
• Fail-fast: EnvironmentError no startup para variáveis obrigatórias

Observabilidade

• Métricas de latência: p50, p95, p99, avg, min, max
• Logging para arquivo: Rotação 10MB, retenção 7 dias, compressão gzip
• Variável: LOG_FILE=/path/to/clickup.log

Segurança

• Sanitização de output: Remove caracteres de controle perigosos
• Truncamento: Outputs limitados a 100k caracteres

Changelog

Ver CHANGELOG.md

Licença

Proprietário - Uso interno

Projeto aprovado pelo Conselho Técnico em 2026-01-10 Sprints 1-5 concluídas em 2026-01-11 Refinamentos (Nota 9+) concluídos em 2026-01-11 Custom Fields (v2.4) concluídos em 2026-01-12 API Completa (v2.5) concluída em 2026-01-12