stevenmcsorley/trello-mcp-server

Trello MCP Server

A comprehensive Model Context Protocol (MCP) server for integrating with Trello. This server enables AI assistants like Claude, Cursor, and other MCP-compatible tools to seamlessly interact with your Trello boards, lists, and cards.

Features

• Board Management: List, create, and manage Trello boards
• List Operations: Create and manage lists on boards
• Card Management: Full CRUD operations for cards (create, read, update, delete, move)
• Label Management: Create, update, and manage labels across boards and cards
• Checklist Support: Create and manage checklists with check items
• Member Management: Add/remove members from boards and cards
• Comments: Add, update, and delete comments on cards
• Attachments: Manage URL attachments on cards
• Kanban View: Get visual kanban-style board views
• Progress Reports: Generate completion statistics for boards
• Real-time Health Checks: Verify Trello API connectivity
• Flexible Configuration: Runtime configuration updates

Installation

npm install
npm run build

Configuration

Get Trello API Credentials

1. Visit https://trello.com/app-key
2. Copy your API key
3. Click the "Token" link to generate your API token
4. Copy the generated token

Set Environment Variables

Create a .env file or export environment variables:

export TRELLO_API_KEY="your-api-key-here"
export TRELLO_API_TOKEN="your-api-token-here"

Or copy .env.example to .env and fill in your credentials:

cp .env.example .env
# Edit .env with your credentials

Usage

Run the Server (stdio)

npm start

Or in development mode:

npm run dev

Integration with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["/absolute/path/to/trello_mcp/dist/index.js"],
      "env": {
        "TRELLO_API_KEY": "your-api-key-here",
        "TRELLO_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Integration with Cursor

Configure in Cursor's MCP settings with the same command and arguments.

Available Tools

Board Management

• list-boards: Get all accessible Trello boards
• get-board: Get detailed information about a specific board
• create-board: Create a new Trello board
• get-board-lists: Get all lists on a board
• create-list: Create a new list on a board

Card Management

• get-card: Get detailed information about a specific card
• list-cards: List all cards on a board or list
• create-card: Create a new card with title, description, due date, labels, and members
• update-card: Update an existing card
• move-card: Move a card to a different list (by ID or name)
• delete-card: Delete a card permanently
• get-kanban-board: Get a kanban-style view of a board
• progress-report: Generate progress statistics for a board

Label Management

• get-board-labels: Get all labels on a board
• create-label: Create a new label with name and color
• update-label: Update label name or color
• delete-label: Delete a label from the board
• add-label-to-card: Add a label to a card
• remove-label-from-card: Remove a label from a card

Checklist Management

• get-card-checklists: Get all checklists on a card
• create-checklist: Create a new checklist on a card
• delete-checklist: Delete a checklist
• add-checklist-item: Add an item to a checklist
• update-checklist-item: Update checklist item state (complete/incomplete)
• delete-checklist-item: Delete a checklist item

Member Management

• get-board-members: Get all members of a board
• get-current-member: Get current authenticated user information
• add-member-to-board: Add a member to a board
• add-member-to-card: Assign a member to a card
• remove-member-from-card: Remove a member from a card

Comments & Attachments

• get-card-comments: Get all comments on a card
• add-comment-to-card: Add a comment to a card
• update-comment: Update an existing comment
• delete-comment: Delete a comment
• get-card-attachments: Get all attachments on a card
• add-attachment-to-card: Add a URL attachment to a card
• delete-attachment: Delete an attachment

Utility Tools

• get-config: Get current server configuration
• update-config: Update server configuration at runtime
• health-check: Check Trello API connectivity
• help: Display help and documentation

Example Workflows

1. Create a New Project Board

1. Use create-board with name="My Project"
2. Use create-list to add lists: "Backlog", "In Progress", "Done"
3. Use create-card to add tasks to the Backlog list

2. Move Tasks Through Workflow

1. Use list-boards to find your board ID
2. Use move-card to move cards from "Backlog" to "In Progress"
3. Use move-card again to move completed cards to "Done"

3. Track Project Progress

1. Use get-kanban-board to see current state
2. Use progress-report to get completion statistics
3. Use list-cards to see all cards on the board

4. Manage Card Details

1. Use create-card with full details (name, description, due date, labels)
2. Use update-card to modify card information
3. Use get-card to retrieve current card state

5. Organize with Labels

1. Use get-board-labels to see available labels
2. Use create-label to add new labels with colors
3. Use add-label-to-card to tag cards

6. Track Tasks with Checklists

1. Use create-checklist on a card
2. Use add-checklist-item to add tasks
3. Use update-checklist-item to check off completed items
4. Use get-card-checklists to view progress

7. Collaborate with Comments

1. Use add-comment-to-card to discuss tasks
2. Use get-card-comments to view conversation
3. Use update-comment to edit your comments

API Reference

Create Card

create-card:
  name: "Card title" (required)
  listId: "list-id" (required)
  desc: "Card description" (optional)
  due: "2025-12-31" (optional, ISO date or date string)
  labels: ["label-id-1", "label-id-2"] (optional)
  members: ["member-id-1"] (optional)
  pos: "top" | "bottom" | number (optional)

Move Card

move-card:
  cardId: "card-id" (required)
  toListId: "target-list-id" (optional if using toListName)
  toListName: "Done" (optional if using toListId, case-insensitive)
  boardId: "board-id" (required when using toListName)

Progress Report

progress-report:
  boardId: "board-id" (required)

Returns:
  - Total cards
  - Cards per list
  - Completed count (lists with "Done" or "Complete" in name)
  - Percentage complete

Development

Project Structure

src/
├── types/
│   └── trello.ts          # TypeScript type definitions
├── services/
│   └── trelloApi.ts       # Trello API service wrapper
├── tools/
│   ├── boardTools.ts      # Board management tools
│   └── cardTools.ts       # Card management tools
├── resources/
│   └── trelloResources.ts # MCP resources (placeholder)
└── index.ts               # Main server entry point

Build

npm run build

Watch Mode

npm run watch

Testing

The server includes a health check tool. After starting, verify connection:

Use the health-check tool to verify Trello API connectivity

Troubleshooting

Connection Issues

1. Verify your API key and token are correct
2. Check internet connectivity
3. Ensure you have access to the Trello API
4. Run health-check tool to diagnose issues

Missing Environment Variables

If you see errors about missing TRELLO_API_KEY or TRELLO_API_TOKEN:

1. Make sure you've set the environment variables
2. Restart Claude Desktop or your MCP client after setting variables
3. Check that the paths in your MCP configuration are correct

Permission Errors

Ensure your Trello API token has the necessary permissions for the operations you want to perform.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License

Credits

Built with:

• @modelcontextprotocol/sdk - MCP TypeScript SDK
• axios - HTTP client
• zod - Schema validation

Resources

• Trello API Documentation
• MCP Protocol Documentation
• Get Trello API Key