Trello MCP Server

🔀 Active fork. This is a maintained fork of kocakli/Trello-Desktop-MCP integrating contributions from across the fork ecosystem (kevinhillinger, zonca, dbz-max, maks244, jantman, ThatIanMcShane, josh-argyle). PRs welcome — see Credits for what each contributor brought in. Published on npm as atlassian-trello-mcp.

A Model Context Protocol (MCP) server for Trello that works with any MCP-compatible client -- Claude Desktop, Claude Code, Gemini CLI, and more.

Provides 46 tools covering boards, cards, lists, labels, checklists, attachments, members, custom fields, and search.

Credentials

Credentials can be provided two ways:

1. Environment variables (recommended): Set TRELLO_API_KEY and TRELLO_TOKEN
2. Per-request: Pass apiKey and token as tool parameters (overrides env vars)

Available Tools (46)

Boards & Lists

Cards

Comments & Activity

Labels

Members on Cards

Attachments

Checklists

Check Items

Search

Development

Project structure

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)

Build & test

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

Key patterns

• ID resolution: All tools accept Trello URLs, short IDs, or full 24-char hex IDs via extractTrelloId()
• Credential fallback: extractCredentials() checks args first, then env vars
• Retry with backoff: TrelloClient retries on 500/network errors (3 attempts, exponential backoff)
• Rate limiting: Extracts and returns x-rate-limit-* headers from every response
• Validation: Zod schemas validate all inputs before API calls

Quick Start

1. Get Trello API credentials

Trello no longer hands out API keys directly — each user must create their own Power-Up, then mint a token against that Power-Up's key.

1. Visit https://trello.com/power-ups/admin and click New.
2. Fill out the New Power-Up or Integration form:
   • New Power-Up or Integration name: Claude MCP. If you have multiple team members, each developer must create their own Power-Up so the API key is tied to their user — name it with your own name too, e.g. Trello MCP Steve.
   • Workspace: the workspace you want to interact with.
   • Iframe connector URL: https://localhost (required field, not actually used by this MCP server).
   • Email: your email.
   • Support contact and Author: can be company-level or personal.
3. Once the Power-Up is created, click API key in the sidebar, then Generate a new API key, then Generate API key in the confirmation modal. Trello displays both an API key and a Secret — save them somewhere safe.
4. In a browser, visit:
   Copy

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

   Replace {NAME} with the Power-Up name you chose and {APIKEY} with the key from the previous step. This is an auth prompt — confirm access and click Allow. Trello returns an API token; copy it.
5. Put the API key and token into your MCP client config (e.g. .claude.json) — see the next section.

2. Install

The easiest path is npx — no clone, no build, just run:

npx atlassian-trello-mcp

Or install from source:

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

3. Configure your MCP client

Edit your config file:

• 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

Set environment variables TRELLO_API_KEY and TRELLO_TOKEN, or pass credentials per-request.

Edit ~/.gemini/settings.json:

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

The server uses stdio transport. Run with environment variables set:

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

Configuration

Read-only mode

Set TRELLO_READ_ONLY=true to disable all write operations. Only read/query tools will be available.

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

Compact mode

Several tools support a compact parameter (default: true) that returns minimal fields to reduce response size. Set compact: false for full details including descriptions, labels, members, and custom fields.

Tools with compact mode: get_board_details, trello_get_board_cards, trello_get_list_cards, trello_search.

Image attachment download

When get_card is called and the card has image attachments, the server downloads them and returns them as inline MCP image content blocks alongside the JSON — letting the client see card images directly. Downloads are restricted to Trello-hosted URLs (*.trello.com, trello-attachments.s3.amazonaws.com) and capped at 5 MB per image to mitigate SSRF and payload-bloat risks.

Set TRELLO_DOWNLOAD_IMAGES=false (or 0/no/off) to disable entirely — the server will skip the extra getCardAttachments call and return text only. Default is enabled.

Logging

Set TRELLO_MCP_LOGGING=true to enable file-based logging via Pino. Logs are written to dist/logs/app.log.

License

MIT