trellio-mcp — Servidor MCP para Trello

Un servidor MCP que proporciona a Claude Desktop, Claude Code y Gemini CLI acceso completo a la API de Trello. Construido sobre la biblioteca cliente asíncrona trellio y el SDK oficial de Python para MCP. Desarrollado siguiendo las Directrices BDD v1.8.0.

Características

• 48 herramientas MCP — mapeo 1:1 con los métodos de trellio, además de una herramienta compuesta get_board_overview

• 2 plantillas de recursos — trello://board/{id} y trello://card/{id} para una carga de contexto enriquecida

• 3 prompts — summarize_board, create_sprint, daily_standup como atajos de flujo de trabajo

• Flujo de autenticación integrado — python -m trello_mcp auth abre el navegador, el usuario hace clic en "Permitir" y el token se almacena de forma segura

• Manejo de errores estructurado — los errores de la API de Trello se traducen en mensajes de error de MCP claros y procesables

• Transporte stdio — se ejecuta como un subproceso local, sin superficie de red

Related MCP server: Trello MCP Server

Herramientas

Las herramientas de tarjetas admiten pos (top/bottom), idLabels (separados por comas), due (ISO 8601) y dueComplete (true/false) al crear y actualizar.

Requisitos previos

• Python 3.10+

• Una clave de API de Trello (añade http://localhost:8095 a los orígenes permitidos)

Instalación

Smithery

npx @smithery/cli install gupta/trellio-mcp --client claude

Usando pipx (recomendado)

Para instalar globalmente de modo que el comando trellio-mcp esté disponible en tu PATH:

pipx install trellio-mcp

Alternativamente, puedes ejecutarlo al vuelo sin instalar:

pipx run trellio-mcp

(Nota: Si usas pipx run, la configuración de tu cliente MCP también debe usar pipx como comando y run trellio-mcp como argumentos.)

Usando pip

pip install trellio-mcp

Desde el código fuente

git clone https://github.com/scaratec/trellio-mcp.git
cd trellio-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Autenticación

Interactiva (recomendado)

Ejecuta el comando de autenticación en cada máquina para conectar tu cuenta de Trello:

Si instalaste globalmente (pipx install o pip install):

TRELLO_API_KEY=your_api_key trellio-mcp auth

Si usas ejecución al vuelo (pipx run):

TRELLO_API_KEY=your_api_key pipx run trellio-mcp auth

Esto abre un navegador donde autorizas la aplicación. El token se captura automáticamente y se almacena en ~/.config/trellio-mcp/credentials.json (permisos 0600).

Después de la autenticación, no se necesitan variables de entorno — el servidor lee las credenciales almacenadas al iniciarse.

Variables de entorno (alternativa)

Si no se encuentran credenciales almacenadas, el servidor recurre a las variables de entorno:

export TRELLO_API_KEY=your_api_key
export TRELLO_TOKEN=your_token

Configuración del cliente MCP

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "trello": {
      "command": "pipx",
      "args": ["run", "trellio-mcp"]
    }
  }
}

Si usas autenticación por variable de entorno en lugar de credenciales almacenadas, añade:

"env": {
  "TRELLO_API_KEY": "your_api_key",
  "TRELLO_TOKEN": "your_token"
}

Claude Code

Añade a ~/.claude/settings.json o al archivo .claude/settings.json del proyecto:

{
  "mcpServers": {
    "trello": {
      "command": "pipx",
      "args": ["run", "trellio-mcp"]
    }
  }
}

Gemini CLI

Añade a ~/.gemini/settings.json:

{
  "mcpServers": {
    "trello": {
      "command": "pipx",
      "args": ["run", "trellio-mcp"]
    }
  }
}

Arquitectura

MCP Client (Claude / Gemini)
    │ stdio (JSON-RPC)
    ▼
trellio-mcp (FastMCP)
    │ async/await
    ▼
trellio (httpx)
    │ HTTPS
    ▼
Trello API

Decisiones clave (documentadas en docs/adr/):

Pruebas

El proyecto utiliza BDD con behave, siguiendo las Directrices BDD v1.8.0.

PYTHONPATH=src .venv/bin/python -m behave

17 features passed, 0 failed, 0 skipped
163 scenarios passed, 0 failed, 0 skipped
970 steps passed, 0 failed, 0 skipped

Arquitectura de pruebas:

• AsyncMock(spec=TrellioClient) — simulación en el límite del cliente, no HTTP

• Validación de persistencia mediante registros de llamadas simuladas (§4.3)

• Evitar hardcoding mediante Scenario Outlines con >= 2 variantes (§2.3)

• Enumeración de rutas de fallo capa por capa (§4.5)

• Auditoría de especificaciones independiente según §13

Consulta el Caso de estudio para una descripción detallada del proceso de desarrollo impulsado por BDD.

Estructura del proyecto

trellio-mcp/
├── src/trello_mcp/
│   ├── __init__.py        # Tool registration
│   ├── __main__.py        # Entry point (server + auth)
│   ├── server.py          # FastMCP instance + client mgmt
│   ├── auth.py            # OAuth flow + credential storage
│   ├── errors.py          # Error translation (ADR 007)
│   ├── tools/             # 10 modules, 48 tools
│   ├── resources.py       # 2 resource templates
│   └── prompts.py         # 3 prompts
├── features/              # 17 BDD feature files
│   └── steps/             # Step definitions
├── docs/
│   ├── adr/               # 7 Architecture Decision Records
│   ├── tool-design.md     # Scenario-driven tool analysis
│   └── case-study-bdd-mcp-server.md
└── pyproject.toml

Publicación

PyPI

uv build
twine upload dist/trellio_mcp-<version>*

Smithery

El espacio de nombres es gupta. Actualiza la versión después de una nueva versión en PyPI:

npx @smithery/cli mcp publish "https://github.com/scaratec/trellio-mcp" -n gupta/trellio-mcp

También actualiza la versión fijada en smithery.yaml en commandFunction.

Licencia

Este proyecto está bajo la Licencia Pública General de GNU v3.0 — consulta el archivo LICENSE para más detalles.