This MCP server provides tools for interacting with Trello boards, handling rate limiting, type safety, and error handling automatically. It offers seamless integration with Trello's API for board management and checklist operations.
The easiest way to use the Trello MCP server is with pnpx
:
{
"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:
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 applicationYOUR_API_KEY
with the API key for your Trello Power-UpIf you prefer using npm directly:
npm install -g @delorenj/mcp-server-trello
Then use npx mcp-server-trello
as the command in your MCP configuration.
To install Trello Server for Claude Desktop automatically:
npx -y @smithery/cli install @delorenj/mcp-server-trello --client claude
For containerized environments:
git clone https://github.com/delorenj/mcp-server-trello
cd mcp-server-trello
cp .env.template .env
docker compose up --build
The server can be configured using environment variables. Create a .env
file with:
# 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
The MCP server supports multiple ways to work with boards:
boardId
parameter{
name: 'list_boards',
arguments: {}
}
{
name: 'set_active_board',
arguments: {
boardId: "abc123" // ID from list_boards response
}
}
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 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)
}
}
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 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 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)
}
}
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)
}
}
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
}
}
Retrieve all lists from a board.
{
name: 'get_lists',
arguments: {
boardId?: string // Optional: ID of the board (uses default if not provided)
}
}
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 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 with time)
start?: string, // Optional: Start date (YYYY-MM-DD format, date only)
labels?: string[] // Optional: Array of label IDs
}
}
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
}
}
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 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
}
}
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 any type of file to a card from a URL or a local file path.
{
name: 'attach_file_to_card',
arguments: {
boardId?: string, // Optional: ID of the board (uses default if not provided)
cardId: string, // 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")
}
}
List all boards the user has access to.
{
name: 'list_boards',
arguments: {}
}
Set the active board for future operations.
{
name: 'set_active_board',
arguments: {
boardId: string // ID of the board to set as active
}
}
List all workspaces the user has access to.
{
name: 'list_workspaces',
arguments: {}
}
The Trello MCP server pairs with the Ideogram MCP server for AI-powered visual content creation. Generate images with Ideogram and attach them directly to your Trello cards!
// Using ideogram-mcp-server
{
name: 'generate_image',
arguments: {
prompt: "A futuristic dashboard design with neon accents",
aspect_ratio: "16:9"
}
}
// Returns: { image_url: "https://..." }
// Using trello-mcp-server
{
name: 'attach_image_to_card',
arguments: {
cardId: "your-card-id",
imageUrl: "https://...", // URL from Ideogram
name: "Dashboard Mockup v1"
}
}
The server implements a token bucket algorithm for rate limiting to comply with Trello's API limits:
Rate limiting is handled automatically, and requests will be queued if limits are reached.
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "trello" '{"command":"npx","args":["-y","@delorenj/mcp-server-trello"]}'
See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json
file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json
file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json
file will be opened and you can add your server like this:
{
"mcpServers": {
"trello": {
"command": "npx",
"args": [
"-y",
"@delorenj/mcp-server-trello"
]
}
}
}
To add an MCP server to a project you can create a new .cursor/mcp.json
file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
~/.config/Claude/claude_desktop_config.json
2. Add this to your configuration file:
{
"mcpServers": {
"trello": {
"command": "npx",
"args": [
"-y",
"@delorenj/mcp-server-trello"
]
}
}
}
3. Restart Claude Desktop for the changes to take effect