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

🚀 Install from MCP Registry (Recommended)

The MCP Server Trello is now available in the official MCP Registry! MCP clients can automatically discover and install this server.

For clients that support the MCP Registry:

Search for "mcp-server-trello" or "io.github.delorenj/mcp-server-trello"
Install directly from the registry
Configure with your Trello credentials

🚀 Quick Start with Bun (Fastest)

If you have Bun installed, using bunx is the fastest way to run the server:

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

Quick Start with npx / pnpx / bunx

You can still use npx or pnpx. This doesn't require a global install and will work just fine, though bunx (above) is faster.

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

Or if you're using mise, you can explicitly execute bunx with mise exec:

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

To connect a Trello workspace, you'll need to manually retrieve a TRELLO_TOKEN once per workspace. After setting up your Trello Power-Up, visit the following URL:

https://trello.com/1/authorize?expiration=never&name=YOUR_APP_NAME&scope=read,write&response_type=token&key=YOUR_API_KEY

Replace:

YOUR_APP_NAME with a name for your application (e.g., "My Trello Integration"). This name is shown to the user on the Trello authorization screen.
YOUR_API_KEY with the API key for your Trello Power-Up

This will generate the token required for integration.

Note

The expiration=never parameter creates a token that does not expire. For enhanced security, consider using expiration=30days and renewing the token periodically if your setup allows for it.

Don't have Bun?

The simplest way to get bun (and thus bunx) is through mise:

# Install mise (if you don't have it)
curl https://mise.run | sh

# Install bun and make the @latest version your system default
mise use bun@latest -g

# Or just run `mise install` from the project directory to install Bun locally
cd /path/to/mcp-server-trello
mise install

Installing via npm

If you prefer using npm directly:

npm install -g @delorenj/mcp-server-trello

(A fast alternative is bun add -g @delorenj/mcp-server-trello)

Then use npx mcp-server-trello as the command in your MCP configuration.

Installing via Smithery

To install Trello Server for Claude Desktop automatically via Smithery:

# Using bunx (recommended)
bunx -y @smithery/cli install @delorenj/mcp-server-trello --client claude

# Using npx
npx -y @smithery/cli install @delorenj/mcp-server-trello --client claude

Docker Installation

For containerized environments:

Clone the repository:

git clone https://github.com/delorenj/mcp-server-trello
cd mcp-server-trello

Copy the environment template and fill in your Trello credentials:

cp .env.template .env

Build and run with Docker Compose:

docker compose up --build

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

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:

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

Start by listing available boards:

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

Set your active board:

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

List workspaces if needed:

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

Set active workspace if needed:

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

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 all items from the "Acceptance Criteria" checklist.

{
  name: 'get_acceptance_criteria',
  arguments: {
    boardId?: string  // Optional: ID of the board (uses default if not provided)
  }
}

get_checklist_by_name

Get a complete checklist with all items and completion percentage.

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

Returns: CheckList object with:

id: Checklist identifier
name: Checklist name
items: Array of CheckListItem objects
percentComplete: Completion percentage (0-100)

get_card 🆕

Get comprehensive details of a specific Trello card with human-level parity.

{
  name: 'get_card',
  arguments: {
    cardId: string,          // ID of the Trello card (short ID like 'FdhbArbK' or full ID)
    includeMarkdown?: boolean // Return formatted markdown instead of JSON (default: false)
  }
}

Returns: Complete card data including:

✅ Checklists with item states and assignments
📎 Attachments with previews and metadata
🏷️ Labels with names and colors
👥 Assigned members
💬 Comments and activity
📊 Statistics (badges)
🎨 Cover images
📍 Board and list context

get_cards_by_list_id

Fetch all cards from a specific list.

{
  name: 'get_cards_by_list_id',
  arguments: {
    boardId?: string, // Optional: ID of the board (uses default if not provided)
    listId: string    // ID of the Trello list
  }
}

get_lists

Retrieve all lists from a board.

{
  name: 'get_lists',
  arguments: {
    boardId?: string  // Optional: ID of the board (uses default if not provided)
  }
}

get_recent_activity

Fetch recent activity on a board.

{
  name: 'get_recent_activity',
  arguments: {
    boardId?: string, // Optional: ID of the board (uses default if not provided)
    limit?: number    // Optional: Number of activities to fetch (default: 10)
  }
}

add_card_to_list

Add a new card to a specified list.

{
  name: 'add_card_to_list',
  arguments: {
    boardId?: string,     // Optional: ID of the board (uses default if not provided)
    listId: string,       // ID of the list to add the card to
    name: string,         // Name of the card
    description?: string, // Optional: Description of the card
  mbs; dueDate?: string,     // Optional: Due date (ISO 8601 format with time)
    start?: string,       // Optional: Start date (YYYY-MM-DD format, date only)
    labels?: string[]     // Optional: Array of label IDs
  }
}

update_card_details

Update an existing card's details.

{
  name: 'update_card_details',
  arguments: {
    boardId?: string,     // Optional: ID of the board (uses default if not provided)
    cardId: string,       // ID of the card to update
    name?: string,        // Optional: New name for the card
    description?: string, // Optional: New description
    dueDate?: string,     // Optional: New due date (ISO 8601 format with time)
    start?: string,       // Optional: New start date (YYYY-MM-DD format, date only)
    dueComplete?: boolean,// Optional: Mark the due date as complete (true) or incomplete (false)
    labels?: string[]     // Optional: New array of label IDs
  }
}

archive_card

Send a card to the archive.

{
  name: 'archive_card',
  arguments: {
    boardId?: string, // Optional: ID of the board (uses default if not provided)
    cardId: string    // ID of the card to archive
  }
}

add_list_to_board

Add a new list to a board.

{
 name: 'add_list_to_board',
  arguments: {
    boardId?: string, // Optional: ID of the board (uses default if not provided)
    name: string      // Name of the new list
  }
}

archive_list

Send a list to the archive.

{
  name: 'archive_list',
  arguments: {
    boardId?: string, // Optional: ID of the board (uses default if not provided)
    listId: string    // ID of the list to archive
  }
}

get_my_cards

Fetch all cards assigned to the current user.

{
  name: 'get_my_cards',
  arguments: {}
}

move_card

Move a card to a different list.

{
  name: 'move_card',
  arguments: {
    boardId?: string,  // Optional: ID of the target board (uses default if not provided)
s;   cardId: string,    // ID of the card to move
    listId: string     // ID of the target list
  }
}

attach_image_to_card

Attach an image to a card directly from a URL.

{
  name: 'attach_image_to_card',
  arguments: {
    boardId?: string, // Optional: ID of the board (uses default if not provided)
    cardId: string,   // ID of the card to attach the image to
    imageUrl: string, // URL of the image to attach
    name?: string     // Optional: Name for the attachment (defaults to "Image Attachment")
  }
}

attach_file_to_card

Attach any type of file to a card from a URL or a local file path (e.g., file:///path/to/your/file.pdf).

{
  name: 'attach_file_to_card',
 arguments: {
    boardId?: string,  // Optional: ID of the board (uses default if not provided)
    cardId: string,s;   // ID of the card to attach the file to
    fileUrl: string,   // URL or local file path (using the file:// protocol) of the file to attach
    name?: string,     // Optional: Name for the attachment (defaults to the file name for local files)
    mimeType?: string  // Optional: MIME type (e.g., "application/pdf", "text/plain", "video/mp4")
  }
}

download_attachment

Download an attachment from a card by ID. Attachment IDs are available in the attachments array returned by get_card.

{
  name: 'download_attachment',
  arguments: {
    cardId: string,       // ID of the card containing the attachment
    attachmentId: string  // ID of the attachment to download
  }
}

Returns: For image attachments (image/*), returns the image as inline viewable data. For all other file types, returns a JSON object with:

fileName: Original filename
mimeType: MIME type of the file
data: Base64-encoded file contents

Comment Management Tools

add_comment

Add a comment to a Trello card.

{
  name: 'add_comment',
  arguments: {
    cardId: string,  // ID of the card to comment on
    text: string     // The text of the comment to add
  }
}

update_comment

Update an existing comment on a card.

{
  name: 'update_comment',
  arguments: {
    commentId: string,  // ID of the comment to change
    text: string        // The new text of the comment
  }
}

delete_comment

Delete a comment from a card.

{
  name: 'delete_comment',
  arguments: {
    commentId: string  // ID of the comment to delete
  }
}

get_card_comments

Retrieve all comments from a specific card without fetching all card data.

{
  name: 'get_card_comments',
  arguments: {
    cardId: string,  // ID of the card to get comments from
    limit?: number   // Optional: Maximum number of comments to retrieve (default: 100)
  }
}

list_boards

List all boards the user has access to.

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

set_active_board

Set the active board for future operations.

{
  name: 'set_active_board',
  arguments: {
    boardId: string  // ID of the board to set as active
  }
}

list_workspaces

List all workspaces the user has access to.

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

set_active_workspace

Set the active workspace for future operations.

{
  name: 'set_active_workspace',
  arguments: {
    workspaceId: string  // ID of the workspace to set as active
  }
}

list_boards_in_workspace

List all boards in a specific workspace.

{
  name: 'list_boards_in_workspace',
  arguments: {
    workspaceId: string  // ID of the workspace to list boards from
  }
}

get_active_board_info

Get information about the currently active board.

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

Custom Field Management Tools

Note: Custom fields require Trello Standard plan or higher.

get_board_custom_fields

Get all custom field definitions on a board. For dropdown/list fields, also returns the available options with their IDs.

{
  name: 'get_board_custom_fields',
  arguments: {
    boardId?: string  // Optional: ID of the board (uses default if not provided)
  }
}

Returns: Array of custom field definitions including:

Field ID, name, type (text, number, checkbox, date, list)
For list type fields: available options with IDs (use these IDs when setting values)

update_card_custom_field

Set or clear a custom field value on a card.

{
  name: 'update_card_custom_field',
  arguments: {
    cardId: string,       // ID of the card to update
    customFieldId: string,// ID of the custom field definition
    type: string,         // Field type: 'text' | 'number' | 'checkbox' | 'date' | 'list' | 'clear'
    value?: string        // The value to set (not needed when type is 'clear')
  }
}

Value format by type:

text: any string
number: numeric string (e.g. "42.5")
checkbox: "true" or "false"
date: ISO 8601 string (e.g. "2025-12-31T00:00:00.000Z")
list: option ID from get_board_custom_fields
clear: omit value to remove the field value

Integration Examples

🎨 Pairing with Ideogram MCP Server

The Trello MCP server pairs beautifully with @flowluap/ideogram-mcp-server for AI-powered visual content creation. Generate images with Ideogram and attach them directly to your Trello cards!

Example Workflow

Generate an image with Ideogram:

// Using ideogram-mcp-server
{
  name: 'generate_image',
  arguments: {
    prompt: "A futuristic dashboard design with neon accents",
    aspect_ratio: "16:9"
  }
}
// Returns: { image_url: "https://..." }

Attach the generated image to a Trello card:

// Using trello-mcp-server
{
  name: 'attach_image_to_card',
  arguments: {
    cardId: "your-card-id",
    imageUrl: "https://...", // URL from Ideogram
    name: "Dashboard Mockup v1"
  }
}

Setting up both servers

Add both servers to your Claude Desktop configuration. Use bunx for the fastest startup.

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

Now you can seamlessly create visual content and organize it in Trello, all within Claude!

Rate Limiting

The server implements a token bucket algorithm for rate limiting to comply with Trello's API limits:

300 requests per 10 seconds per API key
100 requests per 10 seconds per token

Rate limiting is handled automatically, and requests will be queued if limits are reached.

Error Handling

The server provides detailed error messages for various scenarios:

Invalid input parameters
Rate limit exceeded
API authentication errors
Network issues
Invalid board/list/card IDs

Development

Prerequisites

Bun (v1.0.0 or higher)

Setup

Clone the repository

git clone https://github.com/delorenj/mcp-server-trello
cd mcp-server-trello

Install dependencies

bun install

Build the project

bun run build

Running tests

To run the tests, run the following command:

bun test

Running evals

The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the bunx command. Full documentation can be found here.

OPENAI_API_KEY=your-key bunx mcp-eval src/evals/evals.ts src/index.ts

Contributing

Contributions are welcome!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with the Model Context Protocol SDK
Uses the Trello REST API

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.augment		.augment
.claude-flow/metrics		.claude-flow/metrics
.claude		.claude
.gemini		.gemini
.github		.github
.mise		.mise
_bmad-output		_bmad-output
_bmad		_bmad
docs		docs
examples		examples
scripts		scripts
skill		skill
src		src
test		test
tests		tests
.dockerignore		.dockerignore
.env.template		.env.template
.eslintrc.json		.eslintrc.json
.fork-sync-ignore		.fork-sync-ignore
.git-commit-message-generator-config.json		.git-commit-message-generator-config.json
.gitignore		.gitignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile		Dockerfile
Dockerfile.upstream		Dockerfile.upstream
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
bun.lock		bun.lock
compose.yml		compose.yml
example.env		example.env
mise.toml		mise.toml
package.json		package.json
server.js		server.js
server.json		server.json
server.json.bak		server.json.bak
server.json.current		server.json.current
server.schema.json		server.schema.json
smithery.yaml		smithery.yaml
trello-mcp-logo.avif		trello-mcp-logo.avif
tsconfig.json		tsconfig.json
validate-server.mjs		validate-server.mjs
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

MCP Server Trello

Highlights

Changelog

Features

Installation

🚀 Install from MCP Registry (Recommended)

🚀 Quick Start with Bun (Fastest)

Quick Start with npx / pnpx / bunx

Don't have Bun?

Installing via npm

Installing via Smithery

Docker Installation

Configuration

Environment Variables

Board and Workspace Management

Workspace Access Restriction

Example Workflow

Date Format Guidelines

Available Tools

Checklist Management Tools 🆕

get_checklist_items

add_checklist_item

find_checklist_items_by_description

get_acceptance_criteria

get_checklist_by_name

get_card 🆕

get_cards_by_list_id

get_lists

get_recent_activity

add_card_to_list

update_card_details

archive_card

add_list_to_board

archive_list

get_my_cards

move_card

attach_image_to_card

attach_file_to_card

download_attachment

Comment Management Tools

add_comment

update_comment

delete_comment

get_card_comments

list_boards

set_active_board

list_workspaces

set_active_workspace

list_boards_in_workspace

get_active_board_info

Custom Field Management Tools

get_board_custom_fields

update_card_custom_field

Integration Examples

🎨 Pairing with Ideogram MCP Server

Example Workflow

Setting up both servers

Rate Limiting

Error Handling

Development

Prerequisites

Setup

Running tests

Running evals

Contributing

License

Acknowledgments

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors