@asapo/trello-mcp-server

A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with the Trello API to manage cards, lists, and labels on your Trello boards. Perfect for project management automation and team collaboration workflows.

Features

• ✨ Card Management: Create, read, and search cards with full control over position, due dates, members, labels, and location data
• 📋 List Management: Create and retrieve lists from boards with position control
• 🏷️ Label Management: Create and retrieve labels with color customization
• ☑️ Checklist Management: Create checklists with seeded items, add/update/reorder items, mark complete/incomplete
• 🔗 Card Cross-Linking: Attach URLs (or other Trello cards) so they appear as preview chips in the sidebar
• 💬 Comment Integration: Add comments to cards for status updates and team communication
• 🔍 Advanced Search: Search cards across boards or within specific projects with flexible query options
• 📊 Board Analysis: Access board information and analyze project structures
• ⚡ High Performance: Optimized API calls with comprehensive field selection
• 🔒 Secure Authentication: Environment-based API key and token management

Installation

Install the package globally to use with Claude Desktop or Claude Code:

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

Or install locally for development:

npm install @asapo/trello-mcp-server

Configuration

Get Trello API Credentials

1. Get your API key from: https://trello.com/app-key
2. Generate a token using your API key at: https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&name=MCP%20Server&key=YOUR_API_KEY

Environment Setup

Set your Trello credentials as environment variables:

export TRELLO_API_KEY=your_trello_api_key_here
export TRELLO_TOKEN=your_trello_token_here

Or create a .env file:

TRELLO_API_KEY=your_trello_api_key_here
TRELLO_TOKEN=your_trello_token_here

Usage

Quick Setup with Claude MCP

From npm Package

The easiest way to add this server to Claude Desktop or Claude Code:

claude mcp add trello @asapo/trello-mcp-server \
  -e TRELLO_API_KEY=your_api_key_here \
  -e TRELLO_TOKEN=your_token_here

Get your Trello API credentials:

• TRELLO_API_KEY: Get from https://trello.com/app-key
• TRELLO_TOKEN: Generate at https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&name=MCP%20Server&key=YOUR_API_KEY

From Local Clone

If you've cloned the repository for development:

# Clone and setup
git clone [email protected]:wachterjohannes/trello-mcp.git
cd trello-mcp
npm install
npm run build

# Add to Claude with environment variables
claude mcp add trello node $(pwd)/build/index.js \
  -e TRELLO_API_KEY=your_api_key_here \
  -e TRELLO_TOKEN=your_token_here

Or with absolute path:

claude mcp add trello node /absolute/path/to/trello-mcp/build/index.js \
  -e TRELLO_API_KEY=your_api_key_here \
  -e TRELLO_TOKEN=your_token_here

Manual Claude Desktop Integration

Alternatively, manually add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["@asapo/trello-mcp-server"],
      "env": {
        "TRELLO_API_KEY": "your_api_key_here",
        "TRELLO_TOKEN": "your_token_here"
      }
    }
  }
}

Manual Claude Code Integration

Alternatively, manually add to your ~/.claude/settings.json:

{
  "mcp": {
    "servers": {
      "trello": {
        "command": "npx",
        "args": ["@asapo/trello-mcp-server"],
        "env": {
          "TRELLO_API_KEY": "your_api_key_here",
          "TRELLO_TOKEN": "your_token_here"
        }
      }
    }
  }
}

Available Tools

create_card

Create a new card in a Trello list with full parameter support.

// Parameters
{
  "idList": "string",       // Required: Trello list ID
  "name": "string",         // Required: Card title
  "desc": "string?",        // Optional: Card description (supports Markdown)
  "pos": "number|'top'|'bottom'?", // Optional: Position in list
  "due": "string?",         // Optional: Due date (ISO 8601 format)
  "dueComplete": "boolean?", // Optional: Due date completion status
  "idMembers": "string[]?", // Optional: Array of member IDs to assign
  "idLabels": "string[]?",  // Optional: Array of label IDs to attach
  "urlSource": "string?",   // Optional: URL to create card from
  "address": "string?",     // Optional: Physical address
  "locationName": "string?", // Optional: Location name
  "coordinates": "string?"  // Optional: Geographic coordinates (lat,lng)
}

update_card

Update an existing Trello card. All fields are optional except cardId.

// Parameters
{
  "cardId": "string",       // Required: Card ID to update
  "name": "string?",        // Optional: New card title
  "desc": "string?",        // Optional: New description (supports Markdown)
  "closed": "boolean?",     // Optional: Archive status (true/false)
  "idList": "string?",      // Optional: Move to different list
  "idMembers": "string[]?", // Optional: Replace assigned members
  "idLabels": "string[]?",  // Optional: Replace attached labels
  "pos": "number|'top'|'bottom'?", // Optional: New position
  "due": "string|null?",    // Optional: Due date or null to remove
  "dueComplete": "boolean?", // Optional: Mark due date complete
  "subscribed": "boolean?", // Optional: Subscribe to updates
  "address": "string?",     // Optional: Physical address
  "locationName": "string?", // Optional: Location name
  "coordinates": "string?"  // Optional: Geographic coordinates (lat,lng)
}

get_board_cards

Retrieve all cards from a specific Trello board with comprehensive metadata.

// Parameters
{
  "boardId": "string" // Trello board ID
}

get_card_details

Get detailed information about a specific card including members, checklists, and attachments.

// Parameters
{
  "cardId": "string" // Trello card ID
}

get_card_comments

Fetch all comments and discussion history for a card.

// Parameters
{
  "cardId": "string" // Trello card ID
}

add_card_comment

Post a new comment to a Trello card for team collaboration.

// Parameters
{
  "cardId": "string", // Trello card ID
  "comment": "string" // Comment text to add
}

search_cards

Search for cards across boards or within specific projects.

// Parameters
{
  "query": "string",     // Search query
  "boardId": "string?"   // Optional: limit to specific board
}

get_board_lists

Retrieve all lists from a Trello board.

// Parameters
{
  "boardId": "string" // Trello board ID
}

create_list

Create a new list on a Trello board.

// Parameters
{
  "name": "string",         // Required: List name
  "idBoard": "string",      // Required: Trello board ID
  "pos": "number|'top'|'bottom'?" // Optional: Position in board
}

get_board_labels

Retrieve all labels from a Trello board.

// Parameters
{
  "boardId": "string" // Trello board ID
}

create_label

Create a new label on a Trello board.

// Parameters
{
  "name": "string",         // Required: Label name
  "idBoard": "string",      // Required: Trello board ID
  "color": "yellow|purple|blue|red|green|orange|black|sky|pink|lime?" // Optional: Label color
}

get_card_checklists

Get all checklists (with their items) on a Trello card.

// Parameters
{
  "cardId": "string"        // Required: Trello card ID
}

create_checklist

Create a checklist on a card. Optionally seed it with initial items in one call.

// Parameters
{
  "idCard": "string",                  // Required: Card ID to attach the checklist to
  "name": "string",                    // Required: Checklist name
  "pos": "number|'top'|'bottom'?",     // Optional: Position on the card
  "items": "string[]?"                 // Optional: Initial items (created in order, unchecked)
}

add_checklist_item

Add an item to an existing checklist.

// Parameters
{
  "idChecklist": "string",             // Required: Checklist ID
  "name": "string",                    // Required: Item text
  "pos": "number|'top'|'bottom'?",     // Optional: Position within the checklist
  "checked": "boolean?"                // Optional: Initial checked state (default false)
}

update_checklist_item

Update a checklist item — rename, mark complete/incomplete, or reorder.

// Parameters
{
  "idCard": "string",                  // Required: Card ID containing the checklist
  "idCheckItem": "string",             // Required: Checklist item ID
  "name": "string?",                   // Optional: New text
  "state": "'complete'|'incomplete'?", // Optional: Completion state
  "pos": "number|'top'|'bottom'?"      // Optional: New position
}

delete_checklist

Delete a checklist (and all its items) from a card.

// Parameters
{
  "idChecklist": "string"   // Required: Checklist ID
}

attach_card_link

Attach a URL to a card. When the URL points to another Trello card (https://trello.com/c/<shortLink>), Trello renders it as a card-preview chip in the sidebar — useful for cross-linking related cards.

// Parameters
{
  "idCard": "string",   // Required: Card to attach the link to
  "url": "string",      // Required: URL (use a Trello card URL for cross-links)
  "name": "string?"     // Optional: display name for the attachment
}

get_card_attachments

Get all attachments on a card.

// Parameters
{
  "cardId": "string"   // Required: Card ID
}

Example Workflows

Card Creation

Create a new card in list 507f191e810c19729de860ea titled "Implement new feature" with description "Add authentication system" assigned to member 5a2e4b6c8d9e1f2a3b4c5d6e and due date 2024-12-31

Card Updates

Update card abc123 to change title to "Authentication Complete", mark due date as complete, and move to list 507f191e810c19729de860eb

Project Analysis

Analyze all cards in board 507f1f77bcf86cd799439011 and summarize project status

Task Management

Find all overdue cards across my boards and add status update comments

Team Collaboration

Get comments from card abc123 and suggest next steps based on the discussion

Automated Workflows

Create a card for each action item from meeting notes, assign to relevant team members, and set due dates

List Management

Create a new list on board 507f1f77bcf86cd799439011 named "In Review" positioned at the top

Label Organization

Get all labels from board 507f1f77bcf86cd799439011 and create a new "High Priority" label with red color

Development

Local Development

# Clone and setup
git clone [email protected]:wachterjohannes/trello-mcp.git
cd trello-mcp
npm install

# Set environment variables
cp .env.example .env
# Edit .env with your Trello credentials

# Build and run
npm run build
npm start

Available Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Development mode with watch
• npm start - Run the compiled server
• npm run lint - Run ESLint

Project Architecture

src/
├── index.ts          # MCP server implementation
└── trello-client.ts  # Trello API client with TypeScript interfaces

Security

• API credentials are never logged or exposed
• Environment-based authentication prevents credential leakage
• Comprehensive input validation on all tool parameters
• Secure handling of Trello API responses

Troubleshooting

Common Issues

Authentication Errors

Error: TRELLO_API_KEY and TRELLO_TOKEN environment variables are required

→ Ensure your API credentials are properly set in environment variables

Invalid Board/Card IDs

Error: Failed to get board cards: Request failed with status code 400

→ Verify the board or card ID exists and you have access permissions

Rate Limiting

Error: Request failed with status code 429

→ Trello API rate limits apply; implement retry logic or reduce request frequency

Publishing

This package is published to npm as @asapo/trello-mcp-server. To publish updates:

npm version patch|minor|major
npm publish

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

License

MIT License - see LICENSE file for details.