Claude MCP Trello

Claude MCP Trello

Um servidor Model Context Protocol (MCP) que fornece ferramentas para interagir com quadros do Trello. Este servidor permite integração perfeita com a API do Trello, lidando automaticamente com limitação de taxa, segurança de tipos e tratamento de erros.

Recursos

• Integração Completa com Quadros do Trello: Interaja com cartões, listas e atividades do quadro
• Limitação de Taxa Integrada: Respeita os limites da API do Trello (300 requisições/10s por chave de API, 100 requisições/10s por token)
• Implementação Type-Safe: Escrito em TypeScript com definições de tipos abrangentes
• Validação de Entrada: Validação robusta para todas as entradas da API
• Tratamento de Erros: Tratamento de erros elegante com mensagens informativas

Ferramentas Disponíveis

trello_get_cards_by_list

Recupera uma lista de cartões contidos no ID da lista especificada.

{
  name: "trello_get_cards_by_list",
  arguments: {
    listId: string; // Trello list ID
  }
}

trello_get_lists

Recupera todas as listas no quadro especificado.

{
  name: "trello_get_lists",
  arguments: {
    boardId: string; // The ID of the Trello board to get lists from
  }
}

trello_get_recent_activity

Recupera a atividade mais recente de um quadro especificado. O argumento limit pode especificar quantas atividades recuperar (padrão: 10).

{
  name: "trello_get_recent_activity",
  arguments: {
    boardId: string; // The ID of the Trello board to get activity from
    limit?: number;  // Optional: number of activities to retrieve
  }
}

trello_add_card

Adiciona um cartão à lista especificada.

{
  name: "trello_add_card",
  arguments: {
    listId: string;       // The ID of the list to add to
    name: string;         // The title of the card
    description?: string; // Optional: details of the card
    dueDate?: string;     // Optional: due date (e.g., ISO8601)
    labels?: string[];    // Optional: array of label IDs
  }
}

trello_update_card

Atualiza o conteúdo de um cartão.

{
  name: "trello_update_card",
  arguments: {
    cardId: string;       // The ID of the card to be updated
    name?: string;        // Optional: updated title
    description?: string; // Optional: updated description
    dueDate?: string;     // Optional: updated due date (e.g., ISO8601)
    labels?: string[];    // Optional: updated array of label IDs
  }
}

trello_archive_card

Arquiva (fecha) o cartão especificado.

{
  name: "trello_archive_card",
  arguments: {
    cardId: string; // The ID of the card to archive
  }
}

trello_add_list

Adiciona uma nova lista ao quadro especificado.

{
  name: "trello_add_list",
  arguments: {
    boardId: string; // The ID of the Trello board to add the list to
    name: string;    // Name of the new list
  }
}

trello_archive_list

Arquiva (fecha) a lista especificada.

{
  name: "trello_archive_list",
  arguments: {
    listId: string; // The ID of the list to archive
  }
}

trello_get_my_cards

Recupera todos os cartões relacionados à sua conta.

{
  name: "trello_get_my_cards",
  arguments: {}
}

trello_search_all_boards

Realiza uma busca entre quadros em todos os quadros do workspace (organização), dependendo do plano/permissões.

{
  name: "trello_search_all_boards",
  arguments: {
    query: string;   // Search keyword
    limit?: number;  // Optional: max number of results (default: 10)
  }
}

trello_get_card_attachments

Recupera todos os anexos de um cartão especificado. Retorna metadados do anexo, incluindo nome, tamanho do arquivo, tipo MIME e URL. Use isto para descobrir quais anexos existem em um cartão antes de baixar.

{
  name: "trello_get_card_attachments",
  arguments: {
    cardId: string;  // The ID of the Trello card to get attachments from
  }
}

Retorna um array de objetos de anexo com as seguintes propriedades:

• id: Identificador único do anexo
• name: Nome de exibição do anexo
• url: URL para acessar/baixar o anexo
• bytes: Tamanho do anexo em bytes (0 para links externos)
• mimeType: Tipo MIME (ex.: "image/png", "application/pdf")
• date: String de data ISO 8601 quando o anexo foi adicionado
• isUpload: Se é um upload do Trello (true) ou link externo (false)
• fileName: Nome do arquivo do anexo

trello_download_attachment

Baixa um anexo específico de um cartão do Trello. Para arquivos enviados diretamente ao Trello, retorna o conteúdo como dados codificados em base64. Para links externos, retorna a URL.

{
  name: "trello_download_attachment",
  arguments: {
    cardId: string;       // The ID of the Trello card containing the attachment
    attachmentId: string; // The ID of the attachment to download
  }
}

Retorna um objeto com:

• attachment: Os metadados completos do anexo
• content: Conteúdo do arquivo codificado em base64 (para uploads do Trello) ou null (para links externos)
• url: URL direta para o anexo

Dica de uso: Primeiro use trello_get_card_attachments para listar todos os anexos e obter seus IDs, depois use trello_download_attachment para baixar arquivos específicos.

Limitação de Taxa

O servidor implementa um algoritmo de token bucket para limitação de taxa, a fim de cumprir os limites da API do Trello:

• 300 requisições por 10 segundos por chave de API
• 100 requisições por 10 segundos por token

A limitação de taxa é tratada automaticamente, e as requisições serão enfileiradas se os limites forem atingidos.

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para vários cenários:

• Parâmetros de entrada inválidos
• Limite de taxa excedido
• Erros de autenticação da API
• Problemas de rede
• IDs de quadro/lista/cartão inválidos

Desenvolvimento

Pré-requisitos

• Node.js 16 ou superior
• npm ou yarn

Configuração

1. Clone o repositório:

   git clone https://github.com/hrs-asano/claude-mcp-trello.git
   cd claude-mcp-trello
   

2. Instale as dependências:

   npm install
   

3. Compile o projeto:

   npm run build
   

Executando Testes

npm test

Integração com Claude Desktop

Para integrar este servidor MCP com o Claude Desktop, adicione a seguinte configuração ao seu arquivo ~/Library/Application\ Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "trello": {
      "command": "{YOUR_NODE_PATH}", // for example: /opt/homebrew/bin/node
      "args": [
        "{YOUR_PATH}/claude-mcp-trello/build/index.js"
      ],
      "env": {
        "TRELLO_API_KEY": "{YOUR_KEY}",
        "TRELLO_TOKEN": "{YOUR_TOKEN}"
      }
    }
  }
}

Certifique-se de substituir {YOUR_NODE_PATH}, {YOUR_PATH}, {YOUR_KEY} e {YOUR_TOKEN} pelos valores apropriados para o seu ambiente.

Nota: Os IDs dos quadros são passados como parâmetros para ferramentas individuais, em vez de serem configurados globalmente, permitindo que você trabalhe com vários quadros.

Contribuição

Contribuições são bem-vindas! Leia nosso Guia de Contribuição para detalhes sobre nosso código de conduta e o processo para enviar pull requests.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

• Construído com o Model Context Protocol SDK
• Usa a Trello REST API