Servidor MCP de Trello

🔀 Fork activo. Este es un fork mantenido de kocakli/Trello-Desktop-MCP que integra contribuciones de todo el ecosistema de forks (kevinhillinger, zonca, dbz-max, maks244, jantman, ThatIanMcShane, josh-argyle). Las solicitudes de extracción (PRs) son bienvenidas; consulta Créditos para ver lo que aportó cada colaborador. Publicado en npm como atlassian-trello-mcp.

Un servidor del Protocolo de Contexto de Modelo (MCP) para Trello que funciona con cualquier cliente compatible con MCP: Claude Desktop, Claude Code, Gemini CLI y más.

Proporciona 46 herramientas que cubren tableros, tarjetas, listas, etiquetas, listas de verificación, archivos adjuntos, miembros, campos personalizados y búsqueda.

Inicio rápido

1. Obtén las credenciales de la API de Trello

• Visita https://trello.com/app-key

• Copia tu clave de API (API Key)

• Haz clic en "Generate a Token" para obtener acceso de lectura/escritura

2. Instalación

La forma más sencilla es npx: sin clonar, sin compilar, solo ejecuta:

npx atlassian-trello-mcp

O instala desde el código fuente:

git clone https://github.com/agrath/Trello-Desktop-MCP.git
cd Trello-Desktop-MCP
npm install
npm run build

3. Configura tu cliente MCP

Edita tu archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "atlassian-trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-api-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

claude mcp add trello -- npx -y atlassian-trello-mcp

Establece las variables de entorno TRELLO_API_KEY y TRELLO_TOKEN, o pasa las credenciales en cada solicitud.

Edita ~/.gemini/settings.json:

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "atlassian-trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-api-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

El servidor utiliza transporte stdio. Ejecútalo con las variables de entorno configuradas:

TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token npx atlassian-trello-mcp
# or, from a source clone:
TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token node dist/index.js

Related MCP server: fastmcp-trello

Credenciales

Las credenciales se pueden proporcionar de dos maneras:

1. Variables de entorno (recomendado): Establece TRELLO_API_KEY y TRELLO_TOKEN

2. Por solicitud: Pasa apiKey y token como parámetros de la herramienta (sobrescribe las variables de entorno)

Herramientas disponibles (46)

Tableros y listas

Tarjetas

Comentarios y actividad

Etiquetas

Miembros en tarjetas

Archivos adjuntos

Listas de verificación

Elementos de verificación

Búsqueda

Configuración

Modo de solo lectura

Establece TRELLO_READ_ONLY=true para deshabilitar todas las operaciones de escritura. Solo estarán disponibles las herramientas de lectura/consulta.

{
  "env": {
    "TRELLO_API_KEY": "your-key",
    "TRELLO_TOKEN": "your-token",
    "TRELLO_READ_ONLY": "true"
  }
}

Modo compacto

Varias herramientas admiten un parámetro compact (predeterminado: true) que devuelve campos mínimos para reducir el tamaño de la respuesta. Establece compact: false para obtener detalles completos, incluyendo descripciones, etiquetas, miembros y campos personalizados.

Herramientas con modo compacto: get_board_details, trello_get_board_cards, trello_get_list_cards, trello_search.

Descarga de archivos adjuntos de imagen

Cuando se llama a get_card y la tarjeta tiene archivos adjuntos de imagen, el servidor los descarga y los devuelve como bloques de contenido de imagen MCP en línea junto con el JSON, lo que permite al cliente ver las imágenes de la tarjeta directamente. Las descargas están restringidas a URLs alojadas en Trello (*.trello.com, trello-attachments.s3.amazonaws.com) y limitadas a 5 MB por imagen para mitigar los riesgos de SSRF y el aumento excesivo de la carga útil.

Establece TRELLO_DOWNLOAD_IMAGES=false (o 0/no/off) para deshabilitarlo por completo; el servidor omitirá la llamada adicional getCardAttachments y devolverá solo texto. Está habilitado de forma predeterminada.

Registro (Logging)

Establece TRELLO_MCP_LOGGING=true para habilitar el registro basado en archivos a través de Pino. Los registros se escriben en dist/logs/app.log.

Desarrollo

Estructura del proyecto

src/
  index.ts              Entry point (credential injection, tool routing)
  server.ts             MCP server factory (read-only mode support)
  tools/
    boards.ts           Board tools (list, details, lists, filter)
    cards.ts            Card tools (CRUD, archive)
    lists.ts            List tools (cards, create list, comments)
    members.ts          Member tools (user boards, member details)
    search.ts           Search tool
    advanced.ts         Labels, attachments, members on cards, custom fields
    checklists.ts       Checklist and check item tools (13 tools)
  trello/
    client.ts           TrelloClient (API calls, retry, rate limiting)
  types/
    trello.ts           TypeScript interfaces
  utils/
    validation.ts       Zod schemas, extractCredentials, extractTrelloId
    logger.ts           Pino file logger
    health.ts           Health check utility
    appInsights.ts      Telemetry (no-op)
tests/
  validation.test.ts    Validation and credential extraction tests
  trelloClient.test.ts  API client tests (mocked fetch)
  tools.test.ts         Tool handler tests (mocked client)

Compilación y pruebas

npm install
npm run build
npm test
npm run type-check

Patrones clave

• Resolución de ID: Todas las herramientas aceptan URLs de Trello, IDs cortos o IDs hexadecimales completos de 24 caracteres mediante extractTrelloId()

• Respaldo de credenciales: extractCredentials() comprueba primero los argumentos y luego las variables de entorno

• Reintento con retroceso: TrelloClient reintenta en caso de errores 500/red (3 intentos, retroceso exponencial)

• Limitación de tasa: Extrae y devuelve los encabezados x-rate-limit-* de cada respuesta

• Validación: Los esquemas Zod validan todas las entradas antes de las llamadas a la API

Contribución

Las solicitudes de extracción son bienvenidas y se revisan activamente. Este fork es mantenido por un usuario intensivo de Trello, por lo que las funciones se prueban en entornos reales.

Si has hecho un fork del proyecto original y has creado algo útil, por favor envía una PR aquí en lugar de mantener un fork separado; es más fácil para todos beneficiarse de un único proyecto bien mantenido.

Para contribuir:

1. Haz un fork de este repositorio

2. Crea una rama de funciones

3. Añade pruebas para la nueva funcionalidad

4. Ejecuta npm test y npm run build

5. Envía una solicitud de extracción con una descripción clara de qué y por qué

Créditos

Este proyecto es un fork de kocakli/Trello-Desktop-MCP. Se incorporaron funciones e ideas de todo el ecosistema de forks:

• kocakli -- Proyecto original, cambio de marca agnóstico al cliente MCP, corrección de registro en stderr

• kevinhillinger -- Arquitectura de inyección de credenciales, eliminación de etiquetas, gestión de miembros de tarjetas, archivado de tarjetas, tipos de TypeScript expandidos, capa de recursos

• zonca -- Gestión centralizada de credenciales con respaldo de variables de entorno, herramientas de gestión de etiquetas, pruebas unitarias completas, tipos de TypeScript mejorados reemplazando any

• dbz-max -- Soporte para campos personalizados (campos personalizados de tablero + elementos de campo personalizado de tarjeta)

• maks244 -- Concepto de modo de solo lectura, filtrado de listas por nombre, eliminación de credenciales de los registros de telemetría

• jantman -- Corrección para valores numéricos de pos rechazados cuando los clientes MCP los envían como cadenas

• ThatIanMcShane -- Actualización de @modelcontextprotocol/sdk de 1.0.4 a 1.29.0 para corregir tiempos de espera de conexión con las versiones actuales de Claude Code

• josh-argyle -- Descarga automática de archivos adjuntos de imagen en respuestas de get_card como bloques de contenido de imagen MCP en línea (con lista de permitidos + límite de tamaño añadido durante la migración)

Licencia

MIT