Atlassian Trello MCP

Servidor MCP do Trello

🔀 Fork ativo. Este é um fork mantido de kocakli/Trello-Desktop-MCP que integra contribuições de todo o ecossistema de forks (kevinhillinger, zonca, dbz-max, maks244, jantman, ThatIanMcShane, josh-argyle). PRs são bem-vindos — veja Créditos para saber o que cada contribuidor trouxe. Publicado no npm como atlassian-trello-mcp.

Um servidor Model Context Protocol (MCP) para Trello que funciona com qualquer cliente compatível com MCP — Claude Desktop, Claude Code, Gemini CLI e outros.

Fornece 50 ferramentas que cobrem quadros, cartões, listas, etiquetas, checklists, anexos, membros, campos personalizados e pesquisa.

Início Rápido

1. Obtenha as credenciais da API do Trello

O Trello não fornece mais chaves de API diretamente — cada usuário deve criar seu próprio Power-Up e, em seguida, gerar um token vinculado à chave desse Power-Up.

1. Visite https://trello.com/power-ups/admin e clique em Novo.
2. Preencha o formulário Novo Power-Up ou Integração:
   • Nome do Novo Power-Up ou Integração: Claude MCP. Se você tiver vários membros na equipe, cada desenvolvedor deve criar seu próprio Power-Up para que a chave da API esteja vinculada ao seu usuário — inclua também seu próprio nome, por exemplo, Trello MCP Steve.
   • Workspace: o workspace com o qual você deseja interagir.
   • URL do conector do iframe: https://localhost (campo obrigatório, não é realmente usado por este servidor MCP).
   • E-mail: seu e-mail.
   • Contato de suporte e Autor: podem ser em nível de empresa ou pessoal.
3. Após criar o Power-Up, clique em Chave da API na barra lateral, depois em Gerar uma nova chave da API e, em seguida, em Gerar chave da API no modal de confirmação. O Trello exibe tanto uma Chave da API quanto um Segredo — salve-os em um local seguro.
4. Em um navegador, visite:

   https://trello.com/1/authorize?expiration=never&scope=read,write,account&response_type=token&name={NAME}&key={APIKEY}
   

   Substitua {NAME} pelo nome do Power-Up que você escolheu e {APIKEY} pela chave da etapa anterior. Este é um prompt de autenticação — confirme o acesso e clique em Permitir. O Trello retorna um token da API; copie-o.
5. Coloque a chave da API e o token na configuração do seu cliente MCP (por exemplo, .claude.json) — veja a próxima seção.

2. Instalação

O caminho mais fácil é npx — sem clone, sem build, basta executar:

npx atlassian-trello-mcp

Ou instale a partir do código-fonte:

git clone https://github.com/agrath/Trello-Desktop-MCP.git
cd Trello-Desktop-MCP
npm install
npm run build

3. Configure seu cliente MCP

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "atlassian-trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-api-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

claude mcp add trello -- npx -y atlassian-trello-mcp

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "atlassian-trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-api-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token npx atlassian-trello-mcp
# or, from a source clone:
TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token node dist/index.js

Credenciais

As credenciais podem ser fornecidas de duas maneiras:

1. Variáveis de ambiente (recomendado): Defina TRELLO_API_KEY e TRELLO_TOKEN
2. Por solicitação: Passe apiKey e token como parâmetros da ferramenta (substitui as variáveis de ambiente)

Ferramentas Disponíveis (50)

Quadros e Listas

Cartões

Comentários e Atividades

Etiquetas

Membros em Cartões

Anexos

Checklists

Itens de Checklist

Pesquisa

Configuração

Modo somente leitura

Defina TRELLO_READ_ONLY=true para desabilitar todas as operações de escrita. As 25 ferramentas de escrita ficam ocultas de tools/list e são rejeitadas se chamadas mesmo assim, deixando as 25 ferramentas de leitura disponíveis.

A política é uma lista de permissões de ferramentas de leitura, portanto falha de forma fechada: qualquer ferramenta adicionada posteriormente é tratada como escrita até ser explicitamente classificada como leitura.

{
  "env": {
    "TRELLO_API_KEY": "your-key",
    "TRELLO_TOKEN": "your-token",
    "TRELLO_READ_ONLY": "true"
  }
}

Modo compacto

Várias ferramentas suportam um parâmetro compact (padrão: true) que retorna campos mínimos para reduzir o tamanho da resposta. Defina compact: false para obter detalhes completos, incluindo descrições, etiquetas, membros e campos personalizados.

Ferramentas com modo compacto: get_board_details, trello_get_board_cards, trello_get_list_cards, trello_search.

Download de anexos de imagem

Quando get_card é chamado e o cartão tem anexos de imagem, o servidor os baixa e os retorna como blocos de conteúdo de imagem MCP inline junto com o JSON — permitindo que o cliente veja as imagens do cartão diretamente. Os downloads são restritos a URLs hospedadas no Trello (*.trello.com, trello-attachments.s3.amazonaws.com) e limitados a 5 MB por imagem para mitigar riscos de SSRF e inchaço de payload.

Defina TRELLO_DOWNLOAD_IMAGES=false (ou 0/no/off) para desabilitar completamente — o servidor pulará a chamada extra de getCardAttachments e retornará apenas texto. O padrão é habilitado.

Registro de logs

Defina TRELLO_MCP_LOGGING=true para habilitar o registro em arquivo via Pino. Os logs são gravados em dist/logs/app.log.

Desenvolvimento

Estrutura do projeto

src/
  index.ts              Entry point (credential injection, tool routing, read-only enforcement)
  tools/
    boards.ts           Board tools (list, details, lists, filter)
    cards.ts            Card tools (CRUD, archive)
    lists.ts            List tools (cards, create list, comments)
    members.ts          Member tools (user boards, member details)
    search.ts           Search tool
    advanced.ts         Labels, attachments, members on cards, custom fields
    checklists.ts       Checklist and check item tools (13 tools)
  trello/
    client.ts           TrelloClient (API calls, retry, rate limiting)
  types/
    trello.ts           TypeScript interfaces
  utils/
    validation.ts       Zod schemas, extractCredentials, extractTrelloId
    logger.ts           Pino file logger
    readOnly.ts         Read-only mode policy (read-tool allowlist)
    health.ts           Health check utility
    appInsights.ts      Telemetry (no-op)
tests/
  validation.test.ts    Validation and credential extraction tests
  trelloClient.test.ts  API client tests (mocked fetch)
  tools.test.ts         Tool handler tests (mocked client)
  readOnly.test.ts      Read-only mode policy tests

Build e teste

npm install
npm run build
npm test
npm run type-check

Padrões principais

• Resolução de IDs: Todas as ferramentas aceitam URLs do Trello, IDs curtos ou IDs hexadecimais completos de 24 caracteres via extractTrelloId()
• Fallback de credenciais: extractCredentials() verifica os argumentos primeiro, depois as variáveis de ambiente
• Tentativas com backoff: O TrelloClient tenta novamente em erros 500/erros de rede (3 tentativas, backoff exponencial)
• Limitação de taxa: Extrai e retorna cabeçalhos x-rate-limit-* de cada resposta
• Validação: Esquemas Zod validam todas as entradas antes das chamadas à API

Contribuindo

Pull requests são bem-vindos e revisados ativamente. Este fork é mantido por um usuário extensivo do Trello, então os recursos recebem testes no mundo real.

Se você fez um fork do projeto original e construiu algo útil, envie um PR aqui em vez de manter um fork separado — é mais fácil para todos se beneficiarem de um único projeto bem mantido.

Para contribuir:

1. Faça um fork deste repositório
2. Crie um branch de recurso
3. Adicione testes para novas funcionalidades
4. Execute npm test e npm run build
5. Envie um pull request com uma descrição clara do que e porquê

Créditos

Este projeto é um fork de kocakli/Trello-Desktop-MCP. Recursos e ideias foram incorporados de todo o ecossistema de forks:

• kocakli — Projeto original, rebranding agnóstico de cliente MCP, correção de registro de logs em stderr
• kevinhillinger — Arquitetura de injeção de credenciais, exclusão de etiquetas, gerenciamento de membros em cartões, arquivamento de cartões, tipos TypeScript expandidos, camada de recursos
• zonca — Tratamento centralizado de credenciais com fallback de variáveis de ambiente, ferramentas de gerenciamento de etiquetas, testes unitários abrangentes, tipos TypeScript aprimorados substituindo any
• dbz-max — Suporte a campos personalizados (campos personalizados do quadro + itens de campos personalizados do cartão)
• maks244 — Conceito de modo somente leitura, filtragem de listas por nome, remoção de credenciais de logs de telemetria
• jantman — Correção para valores numéricos de pos rejeitados quando enviados como strings por clientes MCP
• ThatIanMcShane — Atualização de @modelcontextprotocol/sdk 1.0.4 → 1.29.0 para corrigir timeouts de conexão com versões atuais do Claude Code
• josh-argyle — Download automático de anexos de imagem em respostas de get_card como blocos de conteúdo de imagem MCP inline (com allowlist e limite de tamanho adicionados durante a portabilidade)
• l-double-l — trello_update_list, trello_get_board_actions com paginação since/before, e a correção de injeção de ID de membro (ampliada durante a portabilidade para validar todos os campos de ID)
• Gileba — Implementação independente de trello_update_list, que informou o formato da ferramenta portada
• TheCodeSharman — idShort (o número de cartão #N local do quadro) exibido em todas as projeções de cartão, e trello_get_card_by_number para resolver um número de cartão citado para um cartão

Licença

MIT