MCP Agile Agent

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

Instalação

Pré-requisito: uv

Único software que precisa estar instalado antes. Sem ele, o comando uvx da Opção A não existe.

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-agile-agent/.env:

uvx --from git+https://github.com/vick1st/mcp-agile-agent mcp-agile-agent 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)

git clone https://github.com/vick1st/mcp-agile-agent
cd mcp-agile-agent
python3 -m venv .venv
source .venv/bin/activate   # Linux/Mac
pip install -e .
mcp-agile-agent setup       # mesmo wizard da opção A

Validar

mcp-agile-agent

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-agile-agent", "mcp-agile-agent"]

As credenciais já ficam salvas em ~/.config/mcp-agile-agent/.env (feito pelo mcp-agile-agent 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):

{
  "mcpServers": {
    "mcp-agile-agent": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vick1st/mcp-agile-agent", "mcp-agile-agent"]
    }
  }
}

Ou via CLI:

opencode mcp add mcp-agile-agent -- uvx --from git+https://github.com/vick1st/mcp-agile-agent mcp-agile-agent

Reinicie a sessão do OpenCode — as tools aparecem automaticamente.

Configurar no Claude Code

.mcp.json (projeto) ou via CLI:

{
  "mcpServers": {
    "mcp-agile-agent": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vick1st/mcp-agile-agent", "mcp-agile-agent"]
    }
  }
}

claude mcp add mcp-agile-agent -- uvx --from git+https://github.com/vick1st/mcp-agile-agent mcp-agile-agent

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):

{
  "mcpServers": {
    "mcp-agile-agent": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vick1st/mcp-agile-agent", "mcp-agile-agent"],
      "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_agile_agent/
├── 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)