Trello MCP服务器

Trello MCP Server

Servidor MCP (Model Context Protocol) para integração completa com o Trello. Gerencie quadros, listas, cards, labels, checklists, comentários, membros, anexos, campos personalizados, webhooks e automações diretamente de assistentes de IA: Claude Code, Claude Desktop, OpenCode ou qualquer cliente MCP via stdio.

• 79 ferramentas, cobrindo boards, listas, cards, labels, checklists, datas, membros, anexos, busca, votos, estatísticas, atividades, power-ups, webhooks, automação e campos personalizados
• 96 testes automatizados com clientes MCP em memória e via stdio, com respostas do Trello simuladas (sem credenciais nem quadros reais)
• TypeScript estrito, SDK oficial do MCP e validação de parâmetros com Zod

Índice

1. Instalação
2. Configuração
3. Obtendo Credenciais
4. Uso nos clientes MCP
5. Todas as Funções
6. Exemplos de Uso
7. Solução de Problemas
8. Desenvolvimento e validação

Instalação

Pré-requisitos

• Node.js 18+ e npm
• Conta no Trello

Passos

git clone https://github.com/SamukDantas/trello-mcp-server.git
cd trello-mcp-server
npm install
npm run build

O build gera dist/index.js, que é o ponto de entrada do servidor.

Configuração

O servidor lê as credenciais de ~/.config/opencode/trello-config.json (no Windows, C:/Users/<você>/.config/opencode/trello-config.json), qualquer que seja o cliente MCP:

{
  "apiKey": "SUA_API_KEY_AQUI",
  "token": "SEU_TOKEN_AQUI",
  "boardId": "ID_DO_QUADRO_PADRAO"
}

As propriedades antigas lists e labels não são utilizadas. Nenhum nome de coluna, ordem de listas ou etiqueta determina o fluxo. O boardId define somente o quadro padrão; boardUrl e trello_set_board permitem escolher outro quadro.

Este arquivo contém credenciais: não o versione. O .gitignore do projeto já ignora *-config.json.

Obtendo Credenciais do Trello

Passo 1: Obter a API Key

1. Acesse: https://trello.com/app-key
2. Faça login na sua conta Trello
3. Copie a "API Key" mostrada na página

Passo 2: Obter o Token de Acesso

Opção 1: Gerar token permanente (Recomendado)

Substitua SUA_API_KEY pela chave obtida no passo anterior e visite:

https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&name=OpenCode-MCP&key=SUA_API_KEY

Opção 2: Usar Trello Power-Up

1. Acesse: https://trello.com/power-ups/admin
2. Crie um novo Power-Up (ou use um existente)
3. Na seção "OAuth", configure como "Default"
4. Generate token

Passo 3: Obter o Board ID

1. Abra seu quadro no Trello
2. A URL será: https://trello.com/b/ABCD1234/nome-do-quadro
3. O Board ID é ABCD1234 (código após /b/)

Passo 4: Obter List IDs

Use o OpenCode para executar:

trello_list_lists

Isso irá mostrar todas as listas e seus IDs.

Uso nos clientes MCP

Nos exemplos, troque /caminho/para pelo diretório onde você clonou o repositório. No Windows, use barras normais (C:/Users/...).

Claude Code

claude mcp add trello -- node /caminho/para/trello-mcp-server/dist/index.js

Claude Desktop

Em claude_desktop_config.json:

{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["/caminho/para/trello-mcp-server/dist/index.js"]
    }
  }
}

OpenCode

Em opencode.json:

{
  "mcp": {
    "trello": {
      "type": "local",
      "command": ["node", "/caminho/para/trello-mcp-server/dist/index.js"],
      "enabled": true
    }
  }
}

Depois de configurar, reinicie o cliente. Para validar as credenciais, peça ao assistente para executar trello_list_boards: se ele listar seus quadros, está tudo certo.

Todas as Funções

Boards (Quadros)

Listas

Cards (Tarefas)

Para ler a descrição de um card, use trello_get_card_details com cardId ou cardName. A resposta inclui todo o texto, preservando Markdown e quebras de linha; descrições vazias são identificadas explicitamente. Não é necessário abrir o navegador para obter o restante da descrição. A confirmação de trello_create_card também inclui a descrição integral.

Após atualizar o código, execute npm run build e reinicie a conexão MCP no cliente para carregar a nova versão.

Labels (Etiquetas)

Checklists

Comentários

Datas de Vencimento

Membros

Arquivos e Anexos

Busca

Votações

Estatísticas

Atividades

Power-Ups

Webhooks

Automação

Export e Templates

Recursos nativos adicionais

As extensões abaixo usam a API REST oficial e ficam em src/platform-tools.ts. Foram priorizadas por cobrir lacunas do MCP: dados estruturados nos cards, recuperação de cards arquivados e acompanhamento individual.

As ferramentas de quadro aceitam boardUrl (URL, ID ou nome); quando omitido, usam o quadro ativo ou o padrão da configuração. As ferramentas de card exigem cardId de 24 caracteres, retornado pelas listagens, e operam diretamente nesse card, independentemente do quadro ativo. Não aceitam nomes parciais.

Exemplos de chamadas MCP (nome da ferramenta seguido dos argumentos JSON):

trello_create_custom_field {"name":"Prioridade","type":"list","options":["Alta","Média","Baixa"]}
trello_list_custom_fields {}
trello_set_card_custom_field {"cardId":"ID_DO_CARD","customFieldId":"ID_DO_CAMPO","value":"ID_DA_OPCAO"}
trello_get_card_custom_fields {"cardId":"ID_DO_CARD"}
trello_set_card_custom_field {"cardId":"ID_DO_CARD","customFieldId":"ID_DO_CAMPO","value":null}
trello_list_archived_cards {}
trello_set_card_archived {"cardId":"ID_DO_CARD","archived":false}
trello_set_card_subscription {"cardId":"ID_DO_CARD","subscribed":true}

Substitua os IDs ilustrativos por IDs reais. Campos number recebem número JSON; checkbox recebe booleano; date recebe ISO 8601 com fuso (por exemplo, 2026-09-22T08:00:00-04:00); list recebe o ID de uma opção existente. null limpa qualquer tipo de campo. A criação de campos list exige opções únicas; outros tipos não aceitam opções. O campo deve pertencer ao quadro do card.

Campos personalizados dependem da disponibilidade do recurso e das permissões no quadro do Trello. As ferramentas retornam falhas com isError: true. Restaurar um card preserva sua lista original; se a lista estiver arquivada, ela precisa ser reaberta no Trello para voltar a aparecer no quadro. Acompanhar afeta somente o usuário autenticado e segue as regras de notificações do Trello.

Referências oficiais:

• Campos personalizados
• API de campos personalizados
• API de cards

Exemplos de Uso

Gerenciamento de Cards

Exemplos de chamadas MCP (não são comandos de terminal). Substitua os IDs pelos valores retornados nas listagens:

trello_list_lists {}
trello_list_cards_in_list {"listName":"Triagem"}
trello_create_card {"name":"Novo pedido","listName":"Triagem","desc":"Descrição do pedido"}
trello_move_card {"cardId":"ID_DO_CARD","listName":"Análise comercial"}
trello_move_card {"cardId":"ID_DO_CARD","listId":"ID_DA_LISTA","boardUrl":"Quadro de destino"}
trello_mark_card_complete {"cardId":"ID_DO_CARD","complete":true}
trello_mark_card_complete {"cardId":"ID_DO_CARD","complete":false}

Listas são selecionadas por ID ou nome exato (ignorando maiúsculas e espaços nas extremidades). Nomes repetidos exigem ID; informar ID e nome incompatíveis gera erro. Criação exige uma lista. Atualização só move quando listId ou listName é informado. A lista deve pertencer ao quadro selecionado. Para mover para outro quadro, selecione esse quadro como destino com boardUrl ou como ativo. Concluir altera apenas dueComplete, sem mover, comentar ou arquivar.

Migração dos atalhos antigos

Os nomes legados continuam disponíveis, mas seus parâmetros mudaram. Chamadas sem card ou lista não escolhem mais uma tarefa ou coluna automaticamente.

trello_create_card, trello_list_cards_in_list, trello_update_list e trello_delete_list também aceitam ID ou nome exato de lista. trello_update_card aceita nome exato do card ou ID; nomes de cards repetidos exigem ID. Nas operações em lote trello_archive_all_cards e trello_delete_all_cards, omitir ambos os filtros de lista opera no quadro inteiro; confirm: true continua obrigatório. Um filtro inválido gera erro.

Trabalhando com Membros

# Listar membros do quadro
trello_list_board_members

# Adicionar membro a um card
trello_add_card_member cardName="Tarefa" memberId="id_do_membro"

Busca e Organização

# Buscar cards por termo
trello_search_cards query="bug"

# Buscar cards por label
trello_search_by_label labelName="Urgente"

# Buscar cards atrasados
trello_search_by_due overdue=true

Estatísticas

# Ver estatisticas do quadro
trello_board_stats

# Ver estatisticas de atividade
trello_board_activity_stats days=30

Arquivos

# Listar anexos de um card
trello_list_attachments cardName="Projeto X"

# Fazer upload de arquivo
trello_upload_attachment cardName="Projeto X" fileUrl="https://exemplo.com/arquivo.pdf"

Webhooks

# Criar webhook para notifications
trello_create_webhook callbackURL="https://meusite.com/webhook" modelId="id_do_board"

# Listar webhooks existentes
trello_list_webhooks

Export

# Exportar quadro
trello_export_board

# Criar quadro a partir de template
trello_create_from_template name="Novo Projeto" templateId="id_do_template"

Solução de Problemas

Erro: "fetch failed" / falha HTTPS

O MCP inclui automaticamente os certificados confiáveis do sistema junto das CAs padrão do Node.js quando o runtime oferece tls.getCACertificates e tls.setDefaultCACertificates. Isso permite usar redes com uma CA local confiável sem desativar a validação HTTPS. Recomendamos Node.js 24 LTS para esse suporte.

Em runtimes antigos, atualize o Node.js ou configure NODE_EXTRA_CA_CERTS com o caminho de um arquivo PEM contendo a CA confiável da sua rede antes de iniciar o MCP. Reinicie a conexão MCP após atualizar.

Falhas de rede agora informam o código da causa (por exemplo, UNABLE_TO_VERIFY_LEAF_SIGNATURE ou ENOTFOUND), sem expor a API key ou o token. Erros de certificado expirado ou hostname incorreto exigem corrigir o certificado.

Erro: "API Key inválida"

• Verifique se a API Key está correta no arquivo de configuração
• Certifique-se de que gerou o token com permissões read,write

Erro: "Token expirado"

• Gere um novo token usando o link com expiration=never
• Atualize o arquivo de configuração

Erro: "Board não encontrado"

• Verifique se o Board ID está correto
• Use trello_list_boards para ver todos os quadros disponíveis

Erro: "Card não encontrado"

• Tente usar o parâmetro cardId em vez de cardName
• Verifique se o card está no quadro correto

Funções não aparecem no cliente MCP

1. Reinicie o cliente MCP
2. Verifique se o caminho para dist/index.js na configuração do cliente está correto
3. Execute npm run build novamente

Debugging

Para verificar se as credenciais estão funcionando:

trello_list_boards

Se retornar uma lista de quadros, as credenciais estão corretas.

Desenvolvimento e validação

npm run build
npm test

Os testes usam clientes MCP em memória e via stdio, com respostas Trello simuladas. Não precisam de credenciais nem acessam quadros reais. Após compilar, reinicie o cliente MCP para carregar as novas ferramentas. O servidor expõe 79 ferramentas.

Licença

MIT © 2026 Samuel Dantas

Contribuição

Issues e pull requests são bem-vindos.