# Trello MCP Server
A Model Context Protocol (MCP) server that provides seamless integration with Trello's API. Manage your Trello boards, lists, and cards directly through Claude or any MCP-compatible client.
## Features
- **Board Management**: List, view, and create Trello boards
- **List Operations**: Create, view, and archive lists on boards
- **Card CRUD**: Full create, read, update, delete operations for cards
- **Card Movement**: Move cards between lists with position control
- **Checklist Management**: Create checklists with items, update progress, and manage checklist items
- **Label Management**: Create, assign, and manage labels on boards and cards
- **Due Date Management**: Set, update, and track due dates on cards
- **Attachment Management**: Upload files, attach URLs, and download attachments from cards
- **Batch Operations**: Create multiple cards or checklist items in a single operation
- **MCP Resources**: Load board, list, and card data into LLM context for analysis
- **Secure Authentication**: API key and token-based authentication via environment variables
## Installation
### Prerequisites
- Python 3.11 or higher
- A Trello account
- Trello API credentials (API key and token)
### Install the Package
```bash
# Clone or download this repository
cd TrelloMCP
# Install using pip
pip install -e .
# Or using uv (recommended)
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e .
```
## Getting Trello API Credentials
### Step 1: Get Your API Key
1. Visit [Trello Power-Ups Admin](https://trello.com/power-ups/admin)
2. Click "New" to create a new Power-Up (if you don't have one)
3. Fill in the required information (name, workspace, etc.)
4. Once created, you'll see your **API Key** on the Power-Up's page
Alternatively, you can get your API key directly from: https://trello.com/app-key
### Step 2: Generate an API Token
1. While viewing your API key page, click the "Token" link or visit:
```
https://trello.com/1/authorize?expiration=never&name=TrelloMCP&scope=read,write&response_type=token&key=YOUR_API_KEY
```
(Replace `YOUR_API_KEY` with the key from Step 1)
2. Click "Allow" to authorize the application
3. Copy the **API Token** that is displayed
### Step 3: Configure Environment Variables
Create a `.env` file in the project root:
```bash
cp .env.example .env
```
Edit `.env` and add your credentials:
```
TRELLO_API_KEY=your_api_key_here
TRELLO_API_TOKEN=your_api_token_here
```
**Important**: Never commit your `.env` file to version control. It's already in `.gitignore`.
## Usage
### Running the Server Standalone
```bash
trello-mcp
```
The server will start and listen for MCP connections via stdio.
### Using with Claude Desktop
Add the following to your Claude Desktop configuration file:
**On macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**On Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"trello": {
"command": "trello-mcp",
"env": {
"TRELLO_API_KEY": "your_api_key_here",
"TRELLO_API_TOKEN": "your_api_token_here"
}
}
}
}
```
Alternatively, if you have a `.env` file in your project directory:
```json
{
"mcpServers": {
"trello": {
"command": "python",
"args": ["-m", "trello_mcp"],
"cwd": "/path/to/TrelloMCP",
"env": {}
}
}
}
```
The server will automatically load credentials from the `.env` file in the working directory.
### Restart Claude Desktop
After updating the configuration, restart Claude Desktop to load the Trello MCP server.
## Available Tools
The server provides the following tools that you can use through natural language with Claude:
### Board Tools
- `list_boards()` - List all your Trello boards
- `get_board(board_id)` - Get details of a specific board
- `create_board(name, desc?)` - Create a new board
### List Tools
- `get_board_lists(board_id)` - Get all lists on a board
- `create_list(board_id, name, pos?)` - Create a new list on a board
- `archive_list(list_id)` - Archive (close) a list
### Card Tools
- `list_cards(list_id)` - Get all cards in a list
- `get_card(card_id)` - Get details of a specific card
- `create_card(list_id, name, desc?, pos?, due?)` - Create a new card
- `create_cards(list_id, cards, delay_ms?)` - Create multiple cards in one operation
- `update_card(card_id, name?, desc?, list_id?, due?, due_complete?)` - Update a card
- `delete_card(card_id)` - Delete a card
- `move_card(card_id, list_id, pos?)` - Move a card to another list
### Checklist Tools
- `get_card_checklists(card_id)` - Get all checklists on a card
- `create_checklist(card_id, name, pos?)` - Create a new checklist on a card
- `get_checklist(checklist_id)` - Get details of a checklist
- `update_checklist(checklist_id, name?, pos?)` - Update a checklist
- `delete_checklist(checklist_id)` - Delete a checklist
- `get_checklist_items(checklist_id)` - Get all items in a checklist
- `add_checklist_item(checklist_id, name, checked?, pos?)` - Add an item to a checklist
- `add_checklist_items(checklist_id, items, delay_ms?)` - Add multiple items to a checklist
- `create_checklist_with_items(card_id, name, items, pos?, delay_ms?)` - Create a checklist with items in one operation
- `update_checklist_item(card_id, checklist_item_id, name?, state?, pos?)` - Update a checklist item
- `delete_checklist_item(checklist_id, checklist_item_id)` - Delete a checklist item
### Label Tools
- `get_board_labels(board_id)` - Get all labels on a board
- `create_label(board_id, name, color?)` - Create a new label on a board
- `update_label(label_id, name?, color?)` - Update a label
- `delete_label(label_id)` - Delete a label
- `get_card_labels(card_id)` - Get all labels assigned to a card
- `add_label_to_card(card_id, label_id)` - Add a label to a card
- `remove_label_from_card(card_id, label_id)` - Remove a label from a card
- `set_card_labels(card_id, label_ids)` - Set all labels on a card (replaces existing)
### Due Date Tools
- `set_card_due_date(card_id, due_date)` - Set or update a card's due date
- `mark_due_date_complete(card_id, complete?)` - Mark due date as complete/incomplete
- `clear_card_due_date(card_id)` - Remove the due date from a card
### Attachment Tools
- `get_card_attachments(card_id)` - Get all attachments on a card
- `get_attachment(card_id, attachment_id)` - Get details of an attachment
- `add_attachment_url(card_id, url, name?)` - Attach a URL to a card
- `add_attachment_file(card_id, file_path, name?)` - Upload a local file as an attachment
- `download_attachment(card_id, attachment_id, output_path)` - Download an attachment to a local file
- `delete_attachment(card_id, attachment_id)` - Delete an attachment
## Available Resources
Resources allow you to load Trello data into the LLM's context for analysis:
- `trello://board/{board_id}` - Load complete board information with all lists and cards
- `trello://list/{list_id}` - Load list information with all cards
- `trello://card/{card_id}` - Load detailed card information
## Example Conversations with Claude
Once configured, you can interact with Trello naturally:
**"Show me all my Trello boards"**
- Claude will call `list_boards()` and display your boards
**"Create a new board called 'Q1 2026 Planning'"**
- Claude will call `create_board(name="Q1 2026 Planning")`
**"On my project board, create a new list called 'In Review'"**
- Claude will first find your board, then call `create_list()`
**"Add a card 'Review design docs' to the To Do list with description 'Need to review the new UI designs'"**
- Claude will call `create_card()` with the appropriate parameters
**"Move that card to the In Progress list"**
- Claude will call `move_card()` to relocate it
**"Load the full context of board abc123"**
- Claude will use the resource `trello://board/abc123` to load all data
**"Create a checklist called 'Launch Tasks' on this card with items for documentation, testing, and deployment"**
- Claude will call `create_checklist_with_items()` to create the checklist with all items at once
**"Add the 'High Priority' label to this card"**
- Claude will find the label ID and call `add_label_to_card()`
**"Set a due date for next Friday on this task"**
- Claude will call `set_card_due_date()` with the appropriate ISO 8601 date
**"Attach this requirements document to the card"**
- Claude will call `add_attachment_file()` to upload the document
**"Create 5 cards for each team member's tasks"**
- Claude will call `create_cards()` to batch create all cards efficiently
## Development
### Running Tests
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
```
### Project Structure
```
TrelloMCP/
├── src/
│ └── trello_mcp/
│ ├── __init__.py
│ ├── __main__.py # Entry point
│ ├── server.py # MCP server with tools and resources
│ └── trello_client.py # Trello API client wrapper
├── tests/
│ ├── __init__.py
│ └── test_server.py
├── pyproject.toml
├── README.md
├── .env.example
└── .gitignore
```
### Adding New Features
1. Add new API methods to `TrelloClient` in `trello_client.py`
2. Add corresponding tools/resources in `server.py` using FastMCP decorators
3. Update this README with the new functionality
## API Rate Limits
Trello's API has rate limits per API key. If you exceed them, you'll receive a 429 error. For frequent updates, consider using Trello webhooks instead of polling.
## Troubleshooting
### "Invalid Trello API credentials" error
- Verify your `TRELLO_API_KEY` and `TRELLO_API_TOKEN` are correct
- Make sure there are no extra spaces or quotes in your `.env` file
- Try regenerating your API token
### "Resource not found" error
- Double-check the board/list/card ID you're using
- Ensure you have access to the resource with your Trello account
### Server not showing in Claude Desktop
- Check that the path to `trello-mcp` is correct
- Verify the JSON syntax in `claude_desktop_config.json`
- Restart Claude Desktop completely
- Check Claude Desktop's logs for error messages
## Security Notes
- Keep your API key and token secure - never commit them to version control
- The `.env` file is automatically ignored by git
- API tokens grant full access to your Trello account - treat them like passwords
- Consider creating a separate Trello workspace for testing
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
## License
MIT License - feel free to use this server for your own projects.
## References
- [Trello REST API Documentation](https://developer.atlassian.com/cloud/trello/rest/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP Framework](https://gofastmcp.com/)
- [Getting Started with Trello REST API](https://support.atlassian.com/trello/docs/getting-started-with-trello-rest-api/)
## Acknowledgments
Built with:
- [FastMCP](https://gofastmcp.com/) - High-level Python SDK for MCP
- [httpx](https://www.python-httpx.org/) - Modern HTTP client
- [python-dotenv](https://github.com/theskumar/python-dotenv) - Environment variable management
