Trello MCP Server

A powerful MCP server for interacting with Trello boards, lists, and cards via AI Hosts.

Quick Start

Option 1: MCP Configuration (Recommended)

The easiest way to use this server is through MCP configuration. This allows your MCP client to automatically manage the Docker container:

1. Get your Trello credentials from Trello Power-Ups Admin

2. Add the configuration to your MCP client's config file:

   For Cursor (~/.cursor/mcp.json):

   {
     "mcpServers": {
       "trello-mcp-server": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "--name", "trello-mcp-server",
           "-e", "TRELLO_API_KEY",
           "-e", "TRELLO_TOKEN",
           "-e", "USE_CLAUDE_APP",
           "-e", "MCP_SERVER_NAME",
           "-e", "MCP_SERVER_HOST",
           "-e", "MCP_SERVER_PORT",
           "ghcr.io/valerok/trello-mcp-server:latest"
         ],
         "env": {
           "TRELLO_API_KEY": "your_trello_api_key_here",
           "TRELLO_TOKEN": "your_trello_token_here",
           "USE_CLAUDE_APP": "false",
           "MCP_SERVER_HOST": "127.0.0.1",
           "MCP_SERVER_PORT": "8952",
           "MCP_SERVER_NAME": "Trello MCP Server"
         }
       }
     }
   }

   For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

   {
     "mcpServers": {
       "trello-mcp-server": {
         "command": "docker",
         "args": [
           "run", "--rm", "-i",
           "--name", "trello-mcp-server",
           "-e", "TRELLO_API_KEY",
           "-e", "TRELLO_TOKEN",
           "-e", "USE_CLAUDE_APP",
           "-e", "MCP_SERVER_NAME",
           "ghcr.io/valerok/trello-mcp-server:latest"
         ],
         "env": {
           "TRELLO_API_KEY": "your_trello_api_key_here",
           "TRELLO_TOKEN": "your_trello_token_here",
           "USE_CLAUDE_APP": "true",
           "MCP_SERVER_NAME": "Trello MCP Server"
         }
       }
     }
   }

3. Restart your MCP client - the server will start automatically!

📖 See MCP_SETUP.md for detailed setup instructions

Option 2: Manual Docker Run

If you prefer to manage the Docker container manually:

1. Create a .env file with your Trello API credentials:

   cp ".env example" .env
   # Edit .env and add your credentials

2. Run the MCP server using Docker:

   docker run \
     --name trello-mcp-server \
     -d \
     --rm \
     --env-file .env \
     --network host \
     -p 8952:8952 \
     ghcr.io/valerok/trello-mcp-server:latest

3. Connect your MCP-compatible client to http://localhost:8952/sse

---

Table of Contents

• Quick Start
• MCP Configuration Setup
• Prerequisites
• Pre-installation
• Installation
• Server Modes
• Configuration
• Client Integration
• Capabilities
• Detailed Capabilities
  • Board Operations
  • List Operations
  • Card Operations
• Usage
• Troubleshooting
• Contributing

---

MCP Configuration Setup

For detailed MCP setup instructions with Docker, see MCP_SETUP.md

This server now supports configuration through MCP config files, where you can:

• Define all environment variables (API keys, tokens) directly in the config
• Let your MCP client automatically manage the Docker container
• No need for separate .env files
• Portable configuration across machines

Example configuration files are provided:

• mcp-config-claude.json - For Claude Desktop
• mcp-config-cursor.json - For Cursor
• mcp-config-example.json - Generic template

Prerequisites

1. Python 3.12 or higher, can easly managed by uv
2. Claude for Desktop installed
3. Trello account and API credentials
4. uv package manager installed

Pre-installation

1. Make sure you have installed Claude Desktop App
2. Make sure you have already logged in with your account into Claude.
3. Start Claude

Installation

1. Set up Trello API credentials:

   • Go to Trello Apps Administration
   • Create a new integration at New Power-Up or Integration
   • Fill in your information (you can leave the Iframe connector URL empty) and make sure to select the correct Workspace
   • Click your app's icon and navigate to "API key" from left sidebar.
   • Copy your "API key" and on the right side: "you can manually generate a Token." click the word token to get your Trello Token.

2. Rename the .env.example file in the project root with .env and set vairables you just got:

TRELLO_API_KEY=your_api_key_here
TRELLO_TOKEN=your_token_here

3. Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

4. Clone this repository:

git clone https://github.com/m0xai/trello-mcp-server.git
cd trello-mcp-server

5. Install dependencies and set server for Claude using uv::

uv run mcp install main.py

6. Restart Claude Desktop app

Server Modes

This MCP server can run in two different modes:

Claude App Mode

This mode integrates directly with the Claude Desktop application:

1. Set USE_CLAUDE_APP=true in your .env file (this is the default)
2. Run the server with:

uv run mcp install main.py

3. Restart the Claude Desktop application

SSE Server Mode

This mode runs as a standalone SSE server that can be used with any MCP-compatible client, including Cursor:

1. Set USE_CLAUDE_APP=false in your .env file
2. Run the server with:

python main.py

3. The server will be available at http://localhost:8952 by default (or your configured port)

Docker Mode

You can also run the server using Docker Compose:

1. Make sure you have Docker and Docker Compose installed
2. Create your .env file with your configuration
3. Build and start the container:

docker-compose up -d

4. The server will run in SSE mode by default
5. To view logs:

docker-compose logs -f

6. To stop the server:

docker-compose down

Resource limits: The container is limited to 256MB RAM by default. Set MCP_DOCKER_MEMORY_LIMIT in your .env (e.g. 128M, 256M, 512M) to change the limit when using Docker Compose or start-mcp-docker.sh.

Pulling the Docker Image (Alternative to Building)

• A pre-built image is available at Docker Hub and is updated automatically by CI:

docker pull ghcr.io/valerok/trello-mcp-server:latest

Then run it with your .env file mounted:

docker run --env-file .env -p 8952:8952 ghcr.io/valerok/trello-mcp-server:latest

How to Prepare Your .env File

1. Get the Example File:

   • In the root of this repository, you will find a file named .env.example.
   • Download or copy this file to your working directory and rename it to .env:

     cp .env.example .env

2. Edit the .env File:

   • Open .env in your favorite text editor.
   • Fill in the required values. At minimum, you need:

     TRELLO_API_KEY=your_trello_api_key_here
     TRELLO_TOKEN=your_trello_token_here
     USE_CLAUDE_APP=false
     MCP_SERVER_HOST=127.0.0.1
     MCP_SERVER_PORT=8952

   • You can get your Trello API key and token by following the instructions in the "Installation" section above.
   • Tip: Never commit your .env file to a public repository, as it contains sensitive credentials.

3. Where to Place the .env File:

   • Place the .env file in the same directory where you run your docker run command.
   • Example directory structure:

     /your/project/
       ├── .env
       └── (other files)
     

4. Full Example Workflow:

   # Clone the repository (optional, for getting the .env.example file)
   git clone https://github.com/m0xai/trello-mcp-server.git
   cd trello-mcp-server
   
   # Copy and edit the .env file
   cp .env.example .env
   # (edit .env with your credentials)
   
   # Pull and run the Docker image
   docker pull ghcr.io/valerok/trello-mcp-server:latest
   docker run --env-file .env -p 8952:8952 ghcr.io/valerok/trello-mcp-server:latest

This allows you to get started quickly without building the image locally.

Configuration

The server can be configured using environment variables in the .env file:

Variable	Description	Default
TRELLO_API_KEY	Your Trello API key	Required
TRELLO_TOKEN	Your Trello API token	Required
MCP_SERVER_NAME	The name of the MCP server	Trello MCP Server
MCP_SERVER_HOST	Host address for SSE mode	127.0.0.1
MCP_SERVER_PORT	Port for SSE mode	8952
USE_CLAUDE_APP	Whether to use Claude app mode	true

You can customize the server by editing these values in your .env file.

Trello API Rate Limiting

This server automatically handles Trello API rate limits as described in the official Trello documentation:

• Trello enforces a limit of 300 requests per 10 seconds per API key, and 100 requests per 10 seconds per token.
• If a rate limit is exceeded, Trello returns a 429 error and may include a Retry-After header.
• The MCP server's Trello API client will automatically detect 429 errors, wait for the appropriate time (using the Retry-After header if present, otherwise using exponential backoff), and retry the request up to 5 times.
• This ensures your requests are less likely to fail due to rate limiting, and you do not need to implement this logic yourself.

Reference: Trello API Rate Limits

Client Integration

Using with Claude Desktop

1. Run the server in Claude app mode (USE_CLAUDE_APP=true)
2. Start or restart Claude Desktop
3. Claude will automatically detect and connect to your MCP server

Using with Cursor

To connect your MCP server to Cursor:

1. Run the server in SSE mode (USE_CLAUDE_APP=false)
2. In Cursor, go to Settings (gear icon) > AI > Model Context Protocol
3. Add a new server with URL http://localhost:8952/sse
4. Select the server when using Cursor's AI features

You can also add this configuration to your Cursor settings JSON file (typically at ~/.cursor/mcp.json):

{
  "mcpServers": {
    "trello-mcp": {
      "url": "http://localhost:8952/sse"
  }
}

Automatic Trello Authorization URL

If the server encounters a 401 Unauthorized error when communicating with the Trello API, it will automatically log a URL that you can visit to authorize the app for your Trello account. This URL is generated using your API key from the .env file and looks like this:

https://trello.com/1/authorize?expiration=never&name=Trello+Assistant+MCP&scope=read,write&response_type=token&key=<YOUR_API_KEY>

How to use:

1. Copy the URL from the server logs when prompted.
2. Open it in your browser and approve the app.
3. Copy the generated token and update your .env file as TRELLO_TOKEN=your_new_token.
4. Restart the server to apply the new token.

This makes it easy to authorize the app for any Trello user without manual URL construction.

Using with Other MCP Clients

For other MCP-compatible clients, point them to the SSE endpoint at http://localhost:8952.

Minimal Client Example

Here's a minimal Python example to connect to the SSE endpoint:

import asyncio
import httpx

async def connect_to_mcp_server():
    url = "http://localhost:8952/sse"
    headers = {"Accept": "text/event-stream"}
    
    async with httpx.AsyncClient() as client:
        async with client.stream("GET", url, headers=headers) as response:
            # Get the session ID from the first SSE message
            session_id = None
            async for line in response.aiter_lines():
                if line.startswith("data:"):
                    data = line[5:].strip()
                    if "session_id=" in data and not session_id:
                        session_id = data.split("session_id=")[1]
                        
                        # Send a message using the session ID
                        message_url = f"http://localhost:8952/messages/?session_id={session_id}"
                        message = {
                            "role": "user",
                            "content": {
                                "type": "text",
                                "text": "Show me my Trello boards"
                            }
                        }
                        await client.post(message_url, json=message)

if __name__ == "__main__":
    asyncio.run(connect_to_mcp_server())

Capabilities

Operation	Board	List	Card	Checklist	Checklist Item
Read	✅	✅	✅	✅	✅
Write	❌	✅	✅	✅	✅
Update	❌	✅	✅	✅	✅
Delete	❌	✅	✅	✅	✅

Detailed Capabilities

Board Operations

• ✅ Read all boards
• ✅ Read specific board details

List Operations

• ✅ Read all lists in a board
• ✅ Read specific list details
• ✅ Create new lists
• ✅ Update list name
• ✅ Archive (delete) lists

Card Operations

• ✅ Read all cards in a list (with optional filtering by creation or last activity date using the from_date parameter)
• ✅ Read specific card details
• ✅ Create new cards
• ✅ Update card attributes
• ✅ Move cards between lists (columns) using the new move_card endpoint/tool
• ✅ Delete cards

Checklist Operations

• ✅ Get a specific checklist
• ✅ List all checklists in a card
• ✅ Create a new checklist
• ✅ Update a checklist
• ✅ Delete a checklist
• ✅ Add checkitem to checklist
• ✅ Update checkitem
• ✅ Delete checkitem

Usage

Once installed, you can interact with your Trello boards through Claude. Here are some example queries:

• "Show me all my boards"
• "What lists are in board [board_name]?"
• "Create a new card in list [list_name] with title [title]"
• "Update the description of card [card_name]"
• "Archive the list [list_name]"
• "Show me all cards in list [list_name] created or updated since 2025-01-01"
• "Move card [card_name] to the [target_list_name] column"

Here are my example usages:

Troubleshooting

If you encounter issues:

1. Verify your Trello API credentials in the .env file
2. Check that you have proper permissions in your Trello workspace
3. Ensure Claude for Desktop is running the latest version
4. Check the logs for any error messages with uv run mcp dev main.py command.
5. Make sure uv is properly installed and in your PATH

Development

Running Tests

This project uses pytest for testing. To run the tests locally:

1. Install development dependencies:

   uv pip install -e ".[dev]"

2. Run tests:

   PYTHONPATH=. uv run pytest tests/

CI/CD

This project uses GitHub Actions for Continuous Integration. The workflow is defined in .github/workflows/ci.yml and runs on every push and pull request to the main branch. It automatically:

• Sets up Python
• Installs dependencies
• Runs the test suite

Contributing

Feel free to submit issues and enhancement requests!

Automatic Trello Authorization URL

If the server encounters a 401 Unauthorized error when communicating with the Trello API, it will automatically log a URL that you can visit to authorize the app for your Trello account. This URL is generated using your API key from the .env file and looks like this:

https://trello.com/1/authorize?expiration=never&name=Trello+Assistant+MCP&scope=read,write&response_type=token&key=<YOUR_API_KEY>

How to use:

1. Copy the URL from the server logs when prompted.
2. Open it in your browser and approve the app.
3. Copy the generated token and update your .env file as TRELLO_TOKEN=your_new_token.
4. Restart the server to apply the new token.

This makes it easy to authorize the app for any Trello user without manual URL construction.

Trello Open API documnetation

https://developer.atlassian.com/cloud/trello/rest/api-group-cards/#api-cards-post 

Trello Open API documnetation