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

1. 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: {} }

1. Set your active board:

{

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

1. List workspaces if needed:

{

name: 'list_workspaces', arguments: {} }

1. Set active workspace if needed:

{

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

1. 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:

• Due Date (`dueDate`): Accepts full ISO 8601 format with time (e.g., 2023-12-31T12:00:00Z)
• Start Date (`start`): Accepts date only in YYYY-MM-DD format (e.g., 2025-08-05)

This distinction follows Trello's API conventions where start dates are day-based markers while due dates can include specific times.

Available Tools

Checklist Management Tools 🆕

get\_checklist\_items

Get all items from a checklist by name.

{

name: 'get_checklist_items', arguments: { name: string,        // Name of the checklist to retrieve items from boardId?: string     // Optional: ID of the board (uses default if not provided) } }

add\_checklist\_item

Add a new item to an existing checklist.

{

name: 'add_checklist_item', arguments: { text: string,           // Text content of the checklist item checkListName: string,  // Name of the checklist to add the item to boardId?: string        // Optional: ID of the board (uses default if not provided) } }

find\_checklist\_items\_by\_description

Search for checklist items containing specific text.

{

name: 'find_checklist_items_by_description', arguments: { description: string,  // Text to search for in checklist item descriptions boardId?: string      // Optional: ID of the board (uses default if not provided) } }

get\_acceptance\_criteria

Get a card's (or board's) acceptance criteria, tolerating the common checklist headings teams actually use. A checklist matches if its name equals Acceptance Criteria, AC, DoD, or Definition of Done — compared case-insensitively and whitespace-trimmed. The first alias in that order with any match wins.

{

name: 'get_acceptance_criteria', arguments: { cardId?: string,  // Optional: ID of the card to scope the search to (recommended to avoid ambiguity) boardId?: string  // Optional: ID of the board (uses default if not provided) } }