Skip to main content
Glama

MCP Server Trello

A Model Context Protocol (MCP) server that provides tools for interacting with Trello boards. This server enables seamless integration with Trello's API while handling rate limiting, type safety, and error handling automatically.

Changelog

1.0.0

  • Fixed MCP protocol compatibility by removing all console output that interfered with JSON-RPC communication

  • Improved pnpx support - now works seamlessly with pnpx @delorenj/mcp-server-trello

  • Updated installation docs to feature pnpx as the primary installation method

  • Added mise installation instructions for convenient tool management

  • Production-ready release with stable API

0.3.0

  • Added multi-board support - all methods now accept optional boardId parameter (thanks @blackoutnet!)

  • TRELLO_BOARD_ID environment variable is now optional and serves as default board

  • Added board and workspace management capabilities:

    • list_boards - List all boards the user has access to

    • set_active_board - Set the active board for future operations

    • list_workspaces - List all workspaces the user has access to

    • set_active_workspace - Set the active workspace for future operations

    • list_boards_in_workspace - List all boards in a specific workspace

    • get_active_board_info - Get information about the currently active board

  • Added persistent configuration storage to remember active board/workspace

  • Improved error handling with MCP-specific error types

  • Full backward compatibility maintained

0.2.1

  • Added detailed JSDoc comments to rate limiter functions

  • Improved error handling for image attachment functionality

  • Updated documentation for attach_image_to_card tool

0.2.0

  • Added attach_image_to_card tool to attach images to cards from URLs

  • Added Docker support with multi-stage build

  • Improved security by moving environment variables to .env

  • Added Docker Compose configuration

  • Added .env.template for easier setup

0.1.1

  • Added move_card tool to move cards between lists

  • Improved documentation

0.1.0

  • Initial release with basic Trello board management features

Related MCP server: MCP Server Trello

Features

  • Full Trello Board Integration: Interact with cards, lists, and board activities

  • 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

Installation

The easiest way to use the Trello MCP server is with pnpx, which doesn't require a global install:

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

Or if you're using mise:

{
  "mcpServers": {
    "trello": {
      "command": "mise",
      "args": ["x", "--", "pnpx", "@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

Theexpiration=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 pnpm?

The simplest way to get pnpm (and thus pnpx) is through mise:

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

# Install pnpm with mise
mise install pnpm

Installing via npm

If you prefer using npm directly:

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

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

Installing via Smithery

To install Trello Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @modelcontextprotocol/mcp-server-trello --client claude

Docker Installation

For containerized environments:

  1. Clone the repository:

git clone https://github.com/delorenj/mcp-server-trello
cd mcp-server-trello
  1. Copy the environment template and fill in your Trello credentials:

cp .env.template .env
  1. 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:

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.

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

Available Tools

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
    dueDate?: string,    // Optional: Due date (ISO 8601 format)
    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)
    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)
    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")
  }
}

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.

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

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

get_board_members

Get all members of a specific board.

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

assign_member_to_card

Assign a member to a specific card.

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

remove_member_from_card

Remove a member from a specific card.

{
  name: 'remove_member_from_card',
  arguments: {
    boardId?: string,  // Optional: ID of the board (uses default if not provided)
    cardId: string,    // ID of the card to remove the member from
    memberId: string   // ID of the member to remove from the card
  }
}

get_board_labels

Get all labels of a specific board.

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

create_label

Create a new label on a board.

{
  name: 'create_label',
  arguments: {
    boardId?: string,  // Optional: ID of the board (uses default if not provided)
    name: string,      // Name of the label
    color?: string     // Optional: Color of the label (e.g., "red", "blue", "green", "yellow", "orange", "purple", "pink", "sky", "lime", "black", "null")
  }
}

update_label

Update an existing label.

{
  name: 'update_label',
  arguments: {
    boardId?: string,  // Optional: ID of the board (uses default if not provided)
    labelId: string,   // ID of the label to update
    name?: string,     // Optional: New name for the label
    color?: string     // Optional: New color for the label
  }
}

delete_label

Delete a label from a board.

{
  name: 'delete_label',
  arguments: {
    boardId?: string,  // Optional: ID of the board (uses default if not provided)
    labelId: string    // ID of the label to delete
  }
}

get_card_history

Get the history/actions of a specific card.

{
  name: 'get_card_history',
  arguments: {
    boardId?: string,  // Optional: ID of the board (uses default if not provided)
    cardId: string,    // ID of the card to get history for
    limit?: number,    // Optional: Number of actions to fetch (default: all)
    filter?: string    // Optional: Filter actions by type (e.g., "all", "updateCard:idList", "addAttachmentToCard", "commentCard", "updateCard:name", "updateCard:desc", "updateCard:due", "addMemberToCard", "removeMemberFromCard", "addLabelToCard", "removeLabelFromCard")
  }
}

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!

Ideogram + Trello Integration Example

Example Workflow

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

{
  "mcpServers": {
    "trello": {
      "command": "pnpx",
      "args": ["@delorenj/mcp-server-trello"],
      "env": {
        "TRELLO_API_KEY": "your-trello-api-key",
        "TRELLO_TOKEN": "your-trello-token"
      }
    },
    "ideogram": {
      "command": "pnpx",
      "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

  • Node.js 16 or higher

  • npm or yarn

Setup

  1. Clone the repository

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

npm install
  1. Build the project

npm run build

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 npx command. Full documentation can be found here.

OPENAI_API_KEY=your-key  npx 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

Available Tools

25 tools
add_card_to_listB

Add a new card to a specified list on a specific board

Inputs: listId (required), name (required), boardId, description, +2 more.

add_list_to_boardB

Add a new list to the specified board

Inputs: name (required), boardId.

archive_cardB

Send a card to the archive on a specific board

Inputs: cardId (required), boardId.

archive_listC

Send a list to the archive on a specific board

Inputs: listId (required), boardId.

assign_member_to_cardB

Assign a member to a specific card

Inputs: cardId (required), memberId (required), boardId.

attach_image_to_cardB

Attach an image to a card from a URL on a specific board

Inputs: cardId (required), imageUrl (required), boardId, name.

create_labelA

Create a new label on a board

Inputs: name (required), boardId, color.

delete_labelC

Delete a label from a board

Inputs: labelId (required), boardId.

get_active_board_infoB

Get information about the currently active board

Inputs: no named parameters.

get_board_labelsA

Get all labels of a specific board

Inputs: boardId.

get_board_membersB

Get all members of a specific board

Inputs: boardId.

get_card_historyB

Get the history/actions of a specific card

Inputs: cardId (required), boardId, limit, filter.

get_cards_by_list_idA

Fetch cards from a specific Trello list on a specific board

Inputs: listId (required), boardId.

get_listsB

Retrieve all lists from the specified board

Inputs: boardId.

get_my_cardsA

Fetch all cards assigned to the current user

Inputs: no named parameters.

get_recent_activityC

Fetch recent activity on the Trello board

Inputs: boardId, limit.

list_boardsB

List all boards the user has access to

Inputs: no named parameters.

list_boards_in_workspaceB

List all boards in a specific workspace

Inputs: workspaceId (required).

list_workspacesA

List all workspaces the user has access to

Inputs: no named parameters.

move_cardA

Move a card to a different list, potentially on a different board

Inputs: cardId (required), listId (required), boardId.

remove_member_from_cardB

Remove a member from a specific card

Inputs: cardId (required), memberId (required), boardId.

set_active_boardB

Set the active board for future operations

Inputs: boardId (required).

set_active_workspaceA

Set the active workspace for future operations

Inputs: workspaceId (required).

update_card_detailsB

Update an existing card's details on a specific board

Inputs: cardId (required), boardId, name, description, +2 more.

update_labelC

Update an existing label

Inputs: labelId (required), boardId, name, color.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools have distinct purposes, but some overlap exists, e.g., between get_cards_by_list_id and get_my_cards, or get_card_history and get_recent_activity. Descriptions help differentiate but minor ambiguity remains.

    Naming Consistency4/5

    Most tool names follow a verb_noun pattern (e.g., add_card_to_list, archive_list). However, there are minor deviations like get_active_board_info (verb_adjective_noun) and get_cards_by_list_id (preposition). Overall consistent.

    Tool Count4/5

    With 25 tools, the server covers a broad Trello domain but feels slightly heavy. Most tools are justified, though some could be combined (e.g., get_board_members vs assign/remove). Still reasonable.

    Completeness3/5

    Covers key CRUD for boards, lists, cards, labels, and members. Notable gaps: no tool to delete a board, list, or card (only archive), and no unarchive operation. Missing update board/list details.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Facilitates interaction with Trello boards via the Trello API, offering features like rate limiting, type safety, input validation, and error handling for seamless management of cards, lists, and board activities.
      5,781 npm
      447
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Trello boards through comprehensive card, list, and board management tools. Includes built-in rate limiting, type safety, and support for operations like creating cards, updating details, managing members, and tracking board activity.
      346 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Trello boards, lists, and cards through the Trello REST API. Supports board management, card operations, member management, labels, and checklists through natural language.
      96 npm
      1
      ISC