MCP Agile Agent

fa# 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.

Related MCP server: Trello MCP Server

Tools

Instalação

1. Dependências

Sempre usar venv — isola as libs do Python global.

cd /caminho/para/mcp-agile-agent
python3 -m venv .venv
source .venv/bin/activate   # Linux/Mac
# .venv\Scripts\activate    # Windows
pip install -r requirements.txt

2. Credenciais Trello

Copie .env.example para .env e preencha:

cp .env.example .env

TRELLO_API_KEY=...
TRELLO_TOKEN=...
TRELLO_BOARD_ID=...
LOG_LEVEL=INFO

Como obter:

1. Acesse https://trello.com/power-ups/admin

2. Crie/abra seu Power-Up → copie a API Key (TRELLO_API_KEY)

3. Gere o token de autenticação abrindo no browser:

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

   Autorize → copie o token → TRELLO_TOKEN

4. TRELLO_BOARD_ID: pegue da URL do board, https://trello.com/b/{BOARD_ID}/nome-do-board

3. Validar setup

.venv/bin/python -c "
import sys; sys.path.insert(0, 'src')
import server
"

Se logar TrelloClient initialized, está ok.

Configurar no OpenCode

Projeto local (opencode.json)

Crie/edite opencode.json na raiz do projeto que usará as tools:

{
  "mcpServers": {
    "mcp-agile-agent": {
      "command": "/caminho/absoluto/para/mcp-agile-agent/.venv/bin/python",
      "args": ["/caminho/absoluto/para/mcp-agile-agent/src/server.py"]
    }
  }
}

Global (CLI)

opencode mcp add mcp-agile-agent -- \
  /caminho/absoluto/para/mcp-agile-agent/.venv/bin/python \
  /caminho/absoluto/para/mcp-agile-agent/src/server.py

.opencode/mcp.json

Ou adicione em ~/.config/opencode/mcp.json:

{
  "mcpServers": {
    "mcp-agile-agent": {
      "command": "/caminho/absoluto/para/mcp-agile-agent/.venv/bin/python",
      "args": ["/caminho/absoluto/para/mcp-agile-agent/src/server.py"]
    }
  }
}

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

Configurar no Claude Code

Projeto local (.mcp.json)

{
  "mcpServers": {
    "mcp-agile-agent": {
      "command": "/caminho/absoluto/para/mcp-agile-agent/.venv/bin/python",
      "args": ["/caminho/absoluto/para/mcp-agile-agent/src/server.py"]
    }
  }
}

Global (CLI)

claude mcp add mcp-agile-agent -- \
  /caminho/absoluto/para/mcp-agile-agent/.venv/bin/python \
  /caminho/absoluto/para/mcp-agile-agent/src/server.py

Configurar no Claude Desktop

Edite ~/.config/claude-desktop/claude_desktop_config.json (Linux) ou equivalente:

{
  "mcpServers": {
    "mcp-agile-agent": {
      "command": "/caminho/absoluto/para/mcp-agile-agent/.venv/bin/python",
      "args": ["/caminho/absoluto/para/mcp-agile-agent/src/server.py"]
    }
  }
}

Troubleshooting

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 — Caminho no config precisa ser absoluto. Reinicie a sessão completamente.

Estrutura

src/
├── server.py            # entry point MCP (protocolo, 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 .env via Pydantic