Atlassian Trello MCP

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). Se aceptan PRs; consulta Créditos para ver qué aportó cada colaborador. Publicado en npm como atlassian-trello-mcp.

Un servidor de Model Context Protocol (MCP) para Trello que funciona con cualquier cliente compatible con MCP: Claude Desktop, Claude Code, Gemini CLI y más.

Proporciona 50 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 credenciales de la API de Trello

Trello ya no entrega claves de API directamente: cada usuario debe crear su propio Power-Up y luego generar un token contra la clave de ese Power-Up.

1. Visita https://trello.com/power-ups/admin y haz clic en Nuevo.
2. Completa el formulario Nuevo Power-Up o Integración:
   • Nombre del nuevo Power-Up o Integración: Claude MCP. Si tienes varios miembros en el equipo, cada desarrollador debe crear su propio Power-Up para que la clave de API esté vinculada a su usuario; incluye también tu nombre, p. ej. Trello MCP Steve.
   • Espacio de trabajo: el espacio de trabajo con el que deseas interactuar.
   • URL del conector iframe: https://localhost (campo obligatorio, aunque este servidor MCP no lo usa realmente).
   • Correo electrónico: tu correo.
   • Contacto de soporte y Autor: pueden ser a nivel de empresa o personales.
3. Una vez creado el Power-Up, haz clic en Clave de API en la barra lateral, luego en Generar una nueva clave de API y después en Generar clave de API en el modal de confirmación. Trello muestra tanto una clave de API como un secreto; guárdalos en un lugar seguro.
4. En un navegador, visita:

   https://trello.com/1/authorize?expiration=never&scope=read,write,account&response_type=token&name={NAME}&key={APIKEY}
   

   Reemplaza {NAME} con el nombre del Power-Up que elegiste y {APIKEY} con la clave del paso anterior. Esto es un aviso de autenticación: confirma el acceso y haz clic en Permitir. Trello devuelve un token de API; cópialo.
5. Coloca la clave de API y el token en la configuración de tu cliente MCP (p. ej. .claude.json); consulta la siguiente sección.

2. Instalación

La vía más sencilla es npx: sin clonar, sin compilar, solo ejecutar:

npx atlassian-trello-mcp

O instalar 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

{
  "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

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

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

Credenciales

Las credenciales se pueden proporcionar de dos maneras:

1. Variables de entorno (recomendado): configura TRELLO_API_KEY y TRELLO_TOKEN
2. Por solicitud: pasa apiKey y token como parámetros de la herramienta (anula las variables de entorno)

Herramientas disponibles (50)

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

Configura TRELLO_READ_ONLY=true para deshabilitar todas las operaciones de escritura. Las 25 herramientas de escritura se ocultan de tools/list y se rechazan si se llaman de todos modos, dejando disponibles las 25 herramientas de lectura.

La política es una lista de permitidos de herramientas de lectura, por lo que falla de forma cerrada: cualquier herramienta agregada posteriormente se trata como escritura hasta que se clasifique explícitamente como lectura.

{
  "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. Configura compact: false para obtener detalles completos, incluidas 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 que el cliente vea las imágenes de la tarjeta directamente. Las descargas se restringen a URL alojadas en Trello (*.trello.com, trello-attachments.s3.amazonaws.com) y se limitan a 5 MB por imagen para mitigar los riesgos de SSRF y de inflado de carga útil.

Configura TRELLO_DOWNLOAD_IMAGES=false (o 0/no/off) para deshabilitar por completo: el servidor omitirá la llamada adicional a getCardAttachments y devolverá solo texto. El valor predeterminado está habilitado.

Registro (logging)

Configura TRELLO_MCP_LOGGING=true para habilitar el registro basado en archivos mediante Pino. Los registros se escriben en dist/logs/app.log.

Desarrollo

Estructura del proyecto

src/
  index.ts              Entry point (credential injection, tool routing, read-only enforcement)
  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
    readOnly.ts         Read-only mode policy (read-tool allowlist)
    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)
  readOnly.test.ts      Read-only mode policy tests

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 URL de Trello, ID cortos o ID hexadecimales completos de 24 caracteres mediante extractTrelloId()
• Respaldo de credenciales: extractCredentials() verifica primero los argumentos y luego las variables de entorno
• Reintento con retroceso: TrelloClient reintenta en errores 500/red (3 intentos, retroceso exponencial)
• Límite de velocidad: 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

Contribuciones

Las solicitudes de extracción (PRs) son bienvenidas y se revisan activamente. Este fork lo mantiene un usuario intensivo de Trello, por lo que las funciones reciben pruebas en el mundo real.

Si has bifurcado el proyecto original y has creado algo útil, envía un PR aquí en lugar de mantener un fork separado: es más fácil que todos se beneficien de un único proyecto bien mantenido.

Para contribuir:

1. Haz un fork de este repositorio
2. Crea una rama de funcionalidad
3. Agrega 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 en tarjetas, archivado de tarjetas, tipos TypeScript ampliados, capa de recursos
• zonca -- Manejo centralizado de credenciales con respaldo de variables de entorno, herramientas de gestión de etiquetas, pruebas unitarias exhaustivas, tipos TypeScript mejorados que reemplazan any
• dbz-max -- Soporte de campos personalizados (campos personalizados del tablero + elementos de campos personalizados de tarjetas)
• maks244 -- Concepto de modo de solo lectura, filtrado de listas por nombre, eliminación de credenciales de registros de telemetría
• jantman -- Corrección para valores numéricos de pos rechazados cuando se enviaban como cadenas por clientes MCP
• ThatIanMcShane -- Actualización de @modelcontextprotocol/sdk 1.0.4 → 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 y límite de tamaño agregados durante el port)
• l-double-l -- trello_update_list, trello_get_board_actions con paginación since/before, y la corrección de inyección de ID de miembro (ampliada durante el port para validar cada campo de ID)
• Gileba -- Implementación independiente de trello_update_list, que informó la forma de la herramienta portada
• TheCodeSharman -- idShort (el número de tarjeta #N local del tablero) expuesto en todas las proyecciones de tarjetas, y trello_get_card_by_number para resolver un número de tarjeta entre comillas a una tarjeta

Licencia

MIT