MCP Server Trello

MCP Server Trello

A Model Context Protocol (MCP) server that gives AI agents full access to your Trello boards — cards, lists, checklists, attachments, comments, custom fields, and workspaces — with built-in rate limiting, type safety, and workflow-level tools you won't find in a plain API wrapper, like acceptance-criteria extraction and checklist dependency queries. 57 tools, one npx install, powered by Bun.

Highlights

• Acceptance criteria, natively: get_acceptance_criteria pulls a card's AC checklist straight into your agent's context — no competitor offers it.
• Watch anything: watch_card and watch_list route card and list activity into your Trello notifications.
• Full list management: create, update, reorder (update_list_position), and archive lists.
• Board and workspace switching on the fly: no restarts, no config edits.
• Rate limiting handled for you: respects Trello's API limits automatically (300 req/10s per key, 100 req/10s per token).
• Bun-powered: fast startup and a 2.8-4.4x performance boost over the old Node build. npx and npm work too.

Changelog

For a detailed list of changes, see CHANGELOG.md.

Features

• Full Trello Board Integration: Interact with cards, lists, and board activities
• Acceptance Criteria Extraction: Pull a card's acceptance criteria checklist directly into agent context
• Checklist Intelligence: Query checklist items by name or description, track completion, manage items
• Complete Card Data Extraction: Fetch all card details including checklists, attachments, labels, members, and comments
• 💬 Comment Management: Add, update, delete, and retrieve comments on cards
• Activity Subscriptions: Watch cards and lists so their activity surfaces in Trello notifications
• List Management: Create, update, reorder, and archive lists
• File Attachments: Attach any type of file to cards (PDFs, documents, videos, images, etc.) from URLs
• Custom Fields: Read board custom field definitions and update card values
• Built-in Rate Limiting: Respects Trello's API limits (300 requests/10s per API key, 100 requests/10s per token)
• Type-Safe Implementation: Written in TypeScript with comprehensive type definitions
• Input Validation: Robust validation for all API inputs
• Error Handling: Graceful error handling with informative messages
• Dynamic Board Selection: Switch between boards and workspaces without restarting
• Markdown Formatting: Export card data in human-readable markdown format

Installation

The server is published on npm as @delorenj/mcp-server-trello. Add it to your MCP client and you're done — no clone, no build.

Quickstart (Claude Desktop, Cursor, and other MCP clients)

Add the server to your client's MCP configuration:

{
  "mcpServers": {
    "trello": {
      "command": "bunx",
      "args": ["@delorenj/mcp-server-trello"],
      "env": {
        "TRELLO_API_KEY": "your-trello-api-key",
        "TRELLO_TOKEN": "your-trello-token"
      }
    }
  }
}

bunx starts fastest, but npx works identically. Get your API key at trello.com/app-key and generate a token from the same page.

Claude Code

Register the server with the CLI:

claude mcp add trello \
  --env TRELLO_API_KEY=your-trello-api-key \
  --env TRELLO_TOKEN=your-trello-token \
  -- bunx @delorenj/mcp-server-trello

MCP Registry

The server is listed on the official MCP Registry as io.github.delorenj/mcp-server-trello, so registry-aware clients can discover and install it directly.

Agent skill package (optional)

This repository also ships a BMAD-compatible skill package for the Trello MCP server. Install the skill/ directory through your agent's skill management workflow, or place it in the agent's skills directory.

When an agent activates the skill, it follows skill/SKILL.md. On first use, the agent runs the bundled installer:

bash skill/scripts/install.sh

The installer builds the MCP server from skill/assets/source/ when Bun is available. If Bun is unavailable, it falls back to the published Smithery install path for @delorenj/mcp-server-trello and creates the same local build/index.js command path used by the skill activation check.

Skill package structure

The skill is the agent-facing entry point for this repository.

• skill/SKILL.md: Activation, routing, and agent workflow rules.
• skill/scripts/install.sh: First-run installer for the bundled server.
• skill/references/trello-mcp/: Focused references for setup, tools, workflows, and gotchas.
• skill/assets/source/: Bundled MCP server source used for local builds.

For AI agents, start with skill/SKILL.md rather than this README. The README is the human-facing overview; the skill references are the operational surface for tool selection and Trello workflow rules.

Maintainers can refresh the bundled source before packaging with:

mise run package

Configuration

Environment Variables

The server can be configured using environment variables. Create a .env file in the root directory with the following variables:

# Required: Your Trello API credentials
TRELLO_API_KEY=your-api-key
TRELLO_TOKEN=your-token

# Optional (Deprecated): Default board ID (can be changed later using set_active_board)
TRELLO_BOARD_ID=your-board-id

# Optional: Initial workspace ID (can be changed later using set_active_workspace)
TRELLO_WORKSPACE_ID=your-workspace-id

# Optional: HTTPS proxy URL (for corporate proxies or restricted networks)
https_proxy=http://your-proxy:8080

# Optional: Restrict access to specific workspaces (comma-separated IDs)
# If set, only the listed workspaces will be accessible via MCP tools
TRELLO_ALLOWED_WORKSPACES=workspace-id-1,workspace-id-2

Proxy Support: If you're behind a corporate proxy or in an environment that routes traffic through a proxy, set the https_proxy or HTTPS_PROXY environment variable. The server will automatically route all Trello API requests through the specified proxy.

You can get these values from:

• API Key: https://trello.com/app-key
• Token: Generate using your API key
• Board ID (optional, deprecated): Found in the board URL (e.g., https://trello.com/b/abc123/example-board)
• Workspace ID: Found in workspace settings or using list_workspaces tool

Board and Workspace Management

Starting with version 0.3.0, the MCP server supports multiple ways to work with boards:

1. Multi-board support: All methods now accept an optional boardId parameter    - Omit TRELLO_BOARD_ID and provide boardId in each API call    - Set TRELLO_BOARD_ID as default and optionally override with boardId parameter

2. Dynamic board selection: Use workspace management tools    - The TRELLO_BOARD_ID in your .env file is used as the initial/default board ID    - You can change the active board at any time using the set_active_board tool    - The selected board persists between server restarts (stored in ~/.trello-mcp/config.json)    - Similarly, you can set and persist an active workspace using set_active_workspace

This allows you to work with multiple boards and workspaces without restarting the server.

Workspace Access Restriction

You can optionally restrict MCP access to specific workspaces using the TRELLO_ALLOWED_WORKSPACES environment variable. This is useful for:

• Security: Limiting AI agent access to only approved workspaces
• Multi-tenant setups: Ensuring agents only access relevant workspaces
• Testing: Isolating test environments from production data

When TRELLO_ALLOWED_WORKSPACES is set:

• list_workspaces only returns workspaces in the allowed list
• list_boards only returns boards from allowed workspaces
• set_active_workspace rejects workspaces not in the allowed list
• list_boards_in_workspace rejects non-allowed workspace IDs
• create_board rejects creation in non-allowed workspaces

Example configuration:

# Only allow access to two specific workspaces
TRELLO_ALLOWED_WORKSPACES=697c549ce04dc460af133a75,5f8a3b2c1d4e5f6a7b8c9d0e

If TRELLO_ALLOWED_WORKSPACES is not set or empty, all workspaces the token has access to will be available (default behaviour).

Example Workflow

1. Start by listing available boards:

{
  name: 'list_boards',
  arguments: {}
}

2. Set your active board:

{
  name: 'set_active_board',
  arguments: {
    boardId: "abc123"  // ID from list_boards response
  }
}

3. List workspaces if needed:

{
  name: 'list_workspaces',
  arguments: {}
}

4. Set active workspace if needed:

{
  name: 'set_active_workspace',
  arguments: {
    workspaceId: "xyz789"  // ID from list_workspaces response
  }
}

5. Check current active board info:

{
  name: 'get_active_board_info',
  arguments: {}
}

Date Format Guidelines

When working with dates in the Trello MCP server, please note the different format requirements: