ClickUp

clickup-mcp-server: Um servidor MCP para ClickUp

Visão Geral

Um servidor Model Context Protocol para interação e automação com a API do ClickUp. Este servidor fornece ferramentas para que sistemas de IA leiam, criem e atualizem tarefas, listas e espaços no ClickUp.

Este servidor MCP permite que ferramentas de IA como o Claude interajam com seu espaço de trabalho no ClickUp, ajudando a automatizar o gerenciamento de tarefas, o planejamento de projetos e outros fluxos de trabalho.

Recursos

Este servidor MCP fornece integração abrangente com o ClickUp, oferecendo os seguintes recursos:

Gerenciamento de Tarefas

• Criar, atualizar e excluir tarefas
• Mover e duplicar tarefas entre listas e quadros
• Definir propriedades de tarefas, incluindo datas de vencimento, prioridades e tags
• Criar, visualizar e gerenciar subtarefas
• Adicionar comentários e anexos às tarefas
• Suporte para operações de tarefas individuais e em lote
• Agrupamento e filtragem de tarefas por status

Organização do Espaço de Trabalho

• Navegar e gerenciar espaços de trabalho, espaços, pastas e listas
• Criar, atualizar e excluir espaços e pastas
• Organizar listas dentro de espaços e pastas
• Visualizar a hierarquia completa do espaço de trabalho
• Navegar com eficiência pelo espaço de trabalho usando notação de caminho
• Criar listas em espaços ou dentro de pastas

Formatação e Exibição

• Suporte completo a Markdown para descrições de tarefas e comentários
• Conversão para HTML para renderização adequada no ClickUp
• Exibição formatada de detalhes de tarefas, listas e hierarquias
• Exibição aprimorada de estruturas de projetos complexas

Experiência do Desenvolvedor

• Tratamento abrangente de erros e validação
• Respostas de API claras e consistentes
• Documentação detalhada para todas as ferramentas
• Integração fácil com o Claude e outros sistemas de IA

Ferramentas

O servidor fornece as seguintes ferramentas para interagir com o ClickUp:

Ferramentas de Espaço de Trabalho/Equipe

1. get_workspaces

   • Obtém todos os espaços de trabalho/equipes
   • Entrada: Nenhuma
   • Retorna: Lista de espaços de trabalho com IDs e nomes

2. navigate_workspace

   • Navega pela hierarquia do espaço de trabalho usando notação de caminho
   • Entrada:
     • path (string): Caminho pela hierarquia do espaço de trabalho (team_id/space_name/folder_name/list_name)
   • Retorna: Detalhes da entidade alvo e seu caminho completo

Ferramentas de Espaço

3. get_spaces

   • Obtém todos os espaços em um espaço de trabalho
   • Entrada:
     • workspace_id (string): ID do espaço de trabalho/equipe
   • Retorna: Lista de espaços com IDs e nomes

4. create_space

   • Cria um novo espaço em um espaço de trabalho
   • Entradas:
     • workspace_id (string): ID do espaço de trabalho/equipe
     • name (string): Nome do novo espaço
   • Retorna: Detalhes do espaço criado

5. get_space_hierarchy

   • Obtém a hierarquia completa de um espaço, incluindo pastas e listas
   • Entrada:
     • space_id (string): ID do espaço
   • Retorna: Estrutura hierárquica completa do espaço

Ferramentas de Pasta

6. get_folders

   • Obtém todas as pastas em um espaço
   • Entrada:
     • space_id (string): ID do espaço
   • Retorna: Lista de pastas com IDs e nomes

7. create_folder

   • Cria uma nova pasta em um espaço
   • Entradas:
     • space_id (string): ID do espaço
     • name (string): Nome da nova pasta
   • Retorna: Detalhes da pasta criada

8. update_folder

   • Atualiza o nome de uma pasta
   • Entradas:
     • folder_id (string): ID da pasta a ser atualizada
     • name (string): Novo nome para a pasta
   • Retorna: Detalhes da pasta atualizada

9. delete_folder

   • Exclui uma pasta
   • Entrada:
     • folder_id (string): ID da pasta a ser excluída
   • Retorna: Confirmação da exclusão

Ferramentas de Lista/Quadro

10. get_lists

    • Obtém todas as listas/quadros em um espaço
    • Entrada:
      • space_id (string): ID do espaço
    • Retorna: Lista de listas/quadros com IDs e nomes

11. create_list

    • Cria uma nova lista/quadro em um espaço ou pasta
    • Entradas:
      • space_id (string): ID do espaço
      • name (string): Nome da nova lista/quadro
      • folder_id (string, opcional): ID da pasta (se a lista estiver sendo criada em uma pasta)
    • Retorna: Detalhes da lista/quadro criada

12. organize_lists

    • Organiza listas por sua localização (no espaço ou em pastas)
    • Entradas:
      • space_id (string): ID do espaço
      • folder_id (string, opcional): ID de uma pasta específica
    • Retorna: Listas organizadas pela pasta que as contém

Ferramentas de Tarefa

13. get_tasks

• Obtém todas as tarefas em uma lista/quadro
• Entrada:
  • list_id (string): ID da lista/quadro
• Retorna: Lista de tarefas com IDs, nomes e outros detalhes

14. get_tasks_by_status

    • Obtém tarefas com um status específico em uma lista/quadro
    • Entradas:
      • list_id (string): ID da lista/quadro
      • status (string): Status para filtrar as tarefas
    • Retorna: Lista de tarefas com o status especificado

15. create_task

    • Cria uma nova tarefa em uma lista/quadro
    • Entradas:
      • list_id (string): ID da lista/quadro
      • name (string): Nome da tarefa
      • description (string, opcional): Descrição da tarefa
      • priority (número, opcional): Prioridade da tarefa (1-4)
      • due_date (número, opcional): Data de vencimento da tarefa em milissegundos
      • tags (string[], opcional): Lista de nomes de tags para adicionar à tarefa
    • Retorna: Detalhes da tarefa criada

16. get_task

    • Obtém detalhes de uma tarefa específica
    • Entrada:
      • task_id (string): ID da tarefa
    • Retorna: Detalhes completos da tarefa, incluindo descrição, status, etc.

17. update_task

    • Atualiza as propriedades de uma tarefa
    • Entradas:
      • task_id (string): ID da tarefa
      • name (string, opcional): Novo nome da tarefa
      • description (string, opcional): Nova descrição da tarefa
      • priority (número, opcional): Nova prioridade da tarefa (1-4)
      • due_date (número, opcional): Nova data de vencimento em milissegundos
      • tags (string[], opcional): Nova lista de nomes de tags
    • Retorna: Detalhes da tarefa atualizada

18. update_task_status

    • Atualiza o status de uma tarefa
    • Entradas:
      • task_id (string): ID da tarefa
      • status (string): Novo status para a tarefa
    • Retorna: Detalhes da tarefa atualizada

19. assign_task

    • Atribui usuários a uma tarefa
    • Entradas:
      • task_id (string): ID da tarefa
      • assignee_ids (string[]): Lista de IDs de usuários para atribuir à tarefa
    • Retorna: Confirmação da atribuição

20. get_task_subtasks

    • Obtém subtarefas de uma tarefa
    • Entrada:
      • task_id (string): ID da tarefa
    • Retorna: Lista de subtarefas com seus detalhes

21. delete_task

    • Exclui uma tarefa
    • Entrada:
      • task_id (string): ID da tarefa a ser excluída
    • Retorna: Confirmação da exclusão

22. move_task

    • Move uma tarefa para uma lista/quadro diferente
    • Entradas:
      • task_id (string): ID da tarefa a ser movida
      • list_id (string): ID da lista/quadro de destino
    • Retorna: Detalhes da tarefa atualizada

23. duplicate_task

    • Duplica uma tarefa, opcionalmente para uma lista/quadro diferente
    • Entradas:
      • task_id (string): ID da tarefa a ser duplicada
      • list_id (string, opcional): ID da lista/quadro de destino
    • Retorna: Detalhes da tarefa duplicada

24. create_subtask

    • Cria uma subtarefa para uma tarefa pai
    • Entradas:
      • parent_task_id (string): ID da tarefa pai
      • name (string): Nome da subtarefa
      • description (string, opcional): Descrição da subtarefa
      • priority (número, opcional): Prioridade da subtarefa (1-4)
      • due_date (número, opcional): Data de vencimento da subtarefa em milissegundos
      • tags (string[], opcional): Lista de nomes de tags para a subtarefa
    • Retorna: Detalhes da subtarefa criada

25. add_comment

    • Adiciona um comentário a uma tarefa
    • Entradas:
      • task_id (string): ID da tarefa
      • comment_text (string): Conteúdo do texto do comentário
    • Retorna: Detalhes do comentário adicionado

26. add_attachment

    • Adiciona um anexo a uma tarefa por URL
    • Entradas:
      • task_id (string): ID da tarefa
      • attachment_url (string): URL do anexo a ser adicionado
    • Retorna: Detalhes do anexo adicionado

27. bulk_update_tasks

    • Atualiza múltiplas tarefas em uma lista de uma só vez
    • Entradas:
      • list_id (string): ID da lista/quadro que contém as tarefas
      • task_ids (string[]): Lista de IDs de tarefas para atualizar
      • name (string, opcional): Novo nome da tarefa para todas as tarefas
      • description (string, opcional): Nova descrição da tarefa para todas as tarefas
      • status (string, opcional): Novo status para todas as tarefas
      • priority (número, opcional): Nova prioridade para todas as tarefas (1-4)
      • due_date (número, opcional): Nova data de vencimento para todas as tarefas em milissegundos
      • tags (string[], opcional): Nova lista de nomes de tags para todas as tarefas
    • Retorna: Confirmação da atualização em lote

28. bulk_delete_tasks

    • Exclui múltiplas tarefas de uma só vez
    • Entrada:
      • task_ids (string[]): Lista de IDs de tarefas para excluir
    • Retorna: Confirmação da exclusão em lote

Ferramentas de Campo Personalizado

29. get_custom_fields

    • Obtém todos os campos personalizados de uma lista/quadro
    • Entrada:
      • list_id (string): ID da lista/quadro
    • Retorna: Lista de campos personalizados com seus IDs, nomes, tipos e configuração

30. set_custom_field_value

    • Define um valor de campo personalizado para uma tarefa usando o ID do campo
    • Entradas:
      • task_id (string): ID da tarefa
      • field_id (string): ID do campo personalizado
      • value (any): Valor a ser definido para o campo personalizado
    • Retorna: Confirmação da atualização do campo personalizado

31. set_custom_field_value_by_name

    • Define um valor de campo personalizado para uma tarefa usando o nome do campo
    • Entradas:
      • task_id (string): ID da tarefa
      • list_id (string): ID da lista (necessário para encontrar o campo personalizado pelo nome)
      • field_name (string): Nome do campo personalizado
      • value (any): Valor a ser definido para o campo personalizado
    • Retorna: Confirmação da atualização do campo personalizado

32. remove_custom_field_value

    • Remove um valor de campo personalizado de uma tarefa
    • Entradas:
      • task_id (string): ID da tarefa
      • field_id (string): ID do campo personalizado
    • Retorna: Confirmação da remoção do campo personalizado

Instalação

Pré-requisitos

• Python 3.10 ou superior
• Uma conta ClickUp com uma chave de API

Usando uv (recomendado)

Ao usar uv, nenhuma instalação específica é necessária. Usaremos uvx para executar diretamente o clickup-mcp-server.

uv --directory "/path/to/clickup-mcp-server" run clickup-mcp-server --api-key YOUR_API_KEY

Ou use um arquivo .env (veja a seção Configuração).

Usando PIP

Alternativamente, você pode instalar o clickup-mcp-server via pip:

pip install clickup-mcp-server

Após a instalação, você pode executá-lo como um script usando:

python -m clickup_mcp_server --api-key YOUR_API_KEY

Configuração

Chave de API

Você precisa de uma chave de API do ClickUp para usar este servidor. Você pode obter uma em Configurações da API do ClickUp.

A chave de API pode ser fornecida de duas maneiras:

1. Argumento de linha de comando: --api-key YOUR_API_KEY
2. Variável de ambiente em um arquivo .env:

   CLICKUP_API_KEY=your_api_key_here
   

Uso com o Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

"mcpServers": {
  "clickup": {
    "command": "uvx",
    "args": ["clickup-mcp-server", "--api-key", "YOUR_API_KEY"]
  }
}

"mcpServers": {
  "clickup": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "CLICKUP_API_KEY=YOUR_API_KEY", "mcp/clickup"]
  }
}

"mcpServers": {
  "clickup": {
    "command": "python",
    "args": ["-m", "clickup_mcp_server", "--api-key", "YOUR_API_KEY"]
  }
}

Uso com o VS Code

Para instalação manual, adicione o seguinte bloco JSON ao seu arquivo de Configurações do Usuário (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open Settings (JSON). Opcionalmente, você pode adicioná-lo a um arquivo chamado .vscode/mcp.json no seu espaço de trabalho. Isso permitirá que você compartilhe a configuração com outras pessoas.

Observe que a chave mcp não é necessária no arquivo .vscode/mcp.json.

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "uvx",
        "args": ["clickup-mcp-server"],
        "env": {
          "CLICKUP_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Para instalação via Docker:

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e", "CLICKUP_API_KEY=YOUR_API_KEY",
          "mcp/clickup"
        ]
      }
    }
  }
}

Uso com Zed

Adicione ao seu settings.json do Zed:

"context_servers": [
  "mcp-server-clickup": {
    "command": {
      "path": "uvx",
      "args": ["clickup-mcp-server"]
    },
    "env": {
      "CLICKUP_API_KEY": "YOUR_API_KEY"
    }
  }
],

"context_servers": {
  "mcp-server-clickup": {
    "command": {
      "path": "python",
      "args": ["-m", "clickup_mcp_server"]
    },
    "env": {
      "CLICKUP_API_KEY": "YOUR_API_KEY"
    }
  }
},

Exemplos de Cenários de Uso

Gerenciamento de Tarefas com Claude

Claude pode ajudar você a gerenciar suas tarefas do ClickUp:

1. Criando um Plano de Tarefa: Peça ao Claude para criar um plano com base em uma tarefa específica no ClickUp. O Claude irá:

   • Encontrar a tarefa por nome ou ID
   • Analisar sua descrição e subtarefas
   • Gerar um plano estruturado para concluir a tarefa

2. Automação de Tarefas: Para uma tarefa contendo instruções relacionadas a código, o Claude pode:

   • Obter os detalhes da tarefa do ClickUp
   • Atualizar o status da tarefa para "Em andamento"
   • Implementar o código de acordo com os requisitos da tarefa
   • Marcar as subtarefas como concluídas à medida que são finalizadas
   • Atualizar o status para "Pronto para revisão" quando terminar

3. Relatórios de Tarefas: Peça ao Claude para gerar resumos de tarefas com status específicos:

   • Obter todas as tarefas marcadas como "Em andamento"
   • Compilar um relatório de status com estimativas de conclusão
   • Criar novas tarefas para bloqueios ou dependências

4. Gerenciamento de Campos Personalizados: Claude pode trabalhar com campos personalizados para melhorar seu fluxo de trabalho:

   • Listar todos os campos personalizados em um projeto para ver os metadados disponíveis
   • Definir valores de campos personalizados como "GitHub Pull Request URL" ao criar PRs
   • Atualizar campos de acompanhamento do projeto como "Sprint", "Story Points" ou "Prioridade"
   • Exemplo: "Crie um PR para este branch e adicione a URL do GitHub ao campo personalizado 'GitHub Pull Request URL' na tarefa relacionada do ClickUp"

Depuração

Execute seu servidor com a flag -v ou -vv para maior verbosidade:

uvx clickup-mcp-server -vv

Você pode usar o inspetor MCP para depurar o servidor:

npx @modelcontextprotocol/inspector uvx clickup-mcp-server

Desenvolvimento

Configurando o Ambiente de Desenvolvimento

1. Clone o repositório:

   git clone https://github.com/yourusername/clickup-mcp-server.git
   cd clickup-mcp-server
   

2. Instale as dependências de desenvolvimento:

   uv pip install -e ".[dev]"
   

3. Execute os testes:

   pytest
   

Build Docker

Construa a imagem Docker:

docker build -t mcp/clickup .

Status de Implementação

Este servidor MCP implementa a maioria dos recursos essenciais do ClickUp. Abaixo está um detalhamento dos recursos implementados e daqueles planejados para implementação futura.

Gerenciamento de Tarefas ✅

Todos os recursos principais de gerenciamento de tarefas foram implementados:

Organização do Espaço de Trabalho ✅

Todos os recursos de organização do espaço de trabalho foram implementados:

Recursos Diversos 🔧

Alguns recursos avançados são implementados, com outros planejados para lançamentos futuros:

Legenda:

• ✅ Implementado
• 🔄 Planejado ou em andamento

Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.