Content
# MCP Trello
Servidor MCP (Model Context Protocol) em Python que expõe operações do Trello como ferramentas para agentes de IA (Claude Code, **OpenCode**, Claude Desktop, Cursor, etc).
## ✨ Diferenciais
- **🧠 Fuzzy Matching Inteligente** — A IA não precisa saber IDs ou nomes exatos. "Move para Sprint Atual" funciona com aproximações.
- **🛠️ Foco em SWE** — Tools pensadas para fluxo de engenharia: criar card em lista por nome, mover entre listas, comentar.
- **Markdown-First** — Respostas limpas, sem ruído.
## Tools
| Tool | Descrição |
| ------------------- | --------------------------------------------------- |
| `create_card` | Cria card em uma lista (por nome) |
| `move_card` | Move card entre listas |
| `add_comment` | Comenta em um card |
| `list_cards` | Lista todos os cards agrupados por lista |
| `board_status` | Resumo: contagem de cards por lista |
| `add_label` | Adiciona um label existente a um card |
| `create_checklist` | Cria um checklist em um card, com itens opcionais |
| `get_card_details` | Detalhes completos de um card (desc, prazo, labels, membros, checklists) |
Todas as tools aceitam `board_name` opcional — se omitido, usa o board padrão configurado em `TRELLO_BOARD_ID`. Passar um nome (com fuzzy matching, igual listas/labels) faz a tool operar em outro board acessível pelo mesmo token.
## Instalação
### Pré-requisito: uv
Único software que precisa estar instalado antes. Sem ele, o comando `uvx` da Opção A não existe.
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
(Windows: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`.) Não precisa instalar Python/pip à parte — o `uv` resolve isso sozinho.
### Opção A — uvx (recomendado, não exige clonar nada)
Rode o wizard interativo — ele explica onde pegar a API Key/Token do Trello e salva tudo em `~/.config/mcp-trello/.env`:
```bash
uvx --from git+https://github.com/vick1st/mcp-trello mcp-trello setup
```
Pronto — nenhum outro passo manual de instalação é necessário. Aponte seu client MCP pro comando abaixo (veja as seções de cada client).
### Opção B — clone local (contribuindo no código)
```bash
git clone https://github.com/vick1st/mcp-trello
cd mcp-trello
python3 -m venv .venv
source .venv/bin/activate # Linux/Mac
pip install -e .
mcp-trello setup # mesmo wizard da opção A
```
### Validar
```bash
mcp-trello
```
Se logar `TrelloClient initialized` e `MCP Trello Server starting...`, está ok (`Ctrl+C` pra sair).
Todos os clients abaixo usam o **mesmo comando**, sem caminho absoluto e sem precisar clonar o repo:
```
command: uvx
args: ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"]
```
As credenciais já ficam salvas em `~/.config/mcp-trello/.env` (feito pelo `mcp-trello setup`), então não precisa repetir chave em cada client — a menos que prefira isolar por projeto (veja alternativa por variável de ambiente abaixo).
## Configurar no OpenCode
`opencode.json` (na raiz do projeto) ou `~/.config/opencode/mcp.json` (global):
```json
{
"mcpServers": {
"mcp-trello": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"]
}
}
}
```
Ou via CLI:
```bash
opencode mcp add mcp-trello -- uvx --from git+https://github.com/vick1st/mcp-trello mcp-trello
```
Reinicie a sessão do OpenCode — as tools aparecem automaticamente.
## Configurar no Claude Code
`.mcp.json` (projeto) ou via CLI:
```json
{
"mcpServers": {
"mcp-trello": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"]
}
}
}
```
```bash
claude mcp add mcp-trello -- uvx --from git+https://github.com/vick1st/mcp-trello mcp-trello
```
## Configurar no Claude Desktop
Último caso — exige gerenciar app nativo. Edite `~/.config/claude-desktop/claude_desktop_config.json` (Linux) ou equivalente com o mesmo bloco `command`/`args` acima.
## Alternativa: credenciais direto no client (sem rodar `setup`)
Se seu client MCP suportar um campo `env` por servidor, dá pra pular o wizard e passar as variáveis direto na config (útil pra CI ou múltiplos boards):
```json
{
"mcpServers": {
"mcp-trello": {
"command": "uvx",
"args": ["--from", "git+https://github.com/vick1st/mcp-trello", "mcp-trello"],
"env": {
"TRELLO_API_KEY": "...",
"TRELLO_TOKEN": "...",
"TRELLO_BOARD_ID": "..."
}
}
}
}
```
**Como obter as credenciais:**
1. Acesse https://trello.com/power-ups/admin
2. Crie/abra seu Power-Up → copie a **API Key**
3. Gere o token abrindo no browser: `https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=SUA_API_KEY` → autorize → copie o token
4. `TRELLO_BOARD_ID`: pegue da URL do board, `https://trello.com/b/{BOARD_ID}/nome-do-board`
## Troubleshooting
**`uvx: command not found`** — Instale o uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`.
**`invalid key` ao chamar qualquer tool** — Key regenerada ou copiada do portal antigo. Confirme em https://trello.com/power-ups/admin.
**`invalid app token` / `token not found`** — Token copiado errado. Não confunda "Segredo" (API secret) com "Token" (gerado via URL de authorize).
**`LIST_NOT_FOUND` / `CARD_NOT_FOUND`** — O fuzzy matching tenta aproximações com cutoff 0.75. Se falhar, use `list_cards` para ver os nomes exatos.
**Claude/OpenCode não enxerga as tools** — Reinicie a sessão completamente após editar a config.
## Estrutura
```
src/mcp_trello/
├── cli.py # entry point do console_script (server ou `setup`)
├── setup_wizard.py # wizard interativo de credenciais
├── server.py # protocolo MCP, registro de tools
├── trello/client.py # HTTP + auth + fuzzy matching com Trello
├── tools/ # handlers async, um por tool MCP
└── config/settings.py # carrega e valida credenciais (env vars / .env)
```
