Trello MCP Server

A Model Context Protocol (MCP) server that provides Claude with tools to interact with Trello boards, lists, and cards through the Trello REST API.

Features

Core Functionality

Board Management: List boards, get board details and metadata
List Operations: Retrieve lists, create new lists within boards
Card Management: Create, update, delete, and move cards between lists
Member Management: Add/remove members from boards and cards
Labels & Checklists: Manage card labels and checklist items

Technical Features

TypeScript implementation with full type safety
Comprehensive error handling and validation
Rate limiting compliance for Trello API
Secure authentication using API key/token
Integration with Popular Agentic IDE via MCP protocol

Prerequisites

Node.js 18+ and npm
Trello account with API access
Claude Desktop application

Installation

Clone the repository:

git clone <repository-url>
cd trello-mcp

Install dependencies:

npm install

Build the project:

npm run build

Authentication Setup

Get Trello API Credentials:
- Visit https://trello.com/app-key to get your API key
- Generate a token by visiting: https://trello.com/1/authorize?expiration=never&scope=read,write,account&response_type=token&name=Server%20Token&key=YOUR_API_KEY

Configure Environment: Create a .env file in the project root:

TRELLO_API_KEY=your_api_key_here
TRELLO_TOKEN=your_token_here

Integration Setup

Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["/path/to/trello-mcp/dist/index.js"],
      "env": {
        "TRELLO_API_KEY": "your_api_key_here",
        "TRELLO_TOKEN": "your_token_here"
      }
    }
  }
}

Docker Desktop Integration

Docker Desktop (v4.38+) includes built-in MCP server support through the Docker MCP Catalog and Toolkit. This provides the easiest way to run and manage MCP servers.

Option 1: Using Docker Desktop's Built-in MCP Support (Recommended)

Enable MCP in Docker Desktop:
- Open Docker Desktop (ensure version 4.38 or later)
- Go to Extensions → Browse → Search for "MCP"
- Install the Docker MCP Catalog and Toolkit extension

Publish to Docker Hub's MCP Catalog:

# Build and tag for MCP catalog
docker build -t mcp/trello-server .
docker push mcp/trello-server

Configure in Claude Desktop with Docker MCP:

{
  "mcpServers": {
    "trello": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", ".env",
        "mcp/trello-server"
      ]
    }
  }
}

Use with Ask Gordon (Docker AI): Create gordon-mcp.yml in your project directory:

version: '3.8'
services:
  trello-mcp:
    image: mcp/trello-server
    environment:
      - TRELLO_API_KEY=${TRELLO_API_KEY}
      - TRELLO_TOKEN=${TRELLO_TOKEN}
    volumes:
      - ./logs:/app/logs

Then use Docker AI commands:

# Ask Gordon to help with Trello management
docker ai "Show me my Trello boards and create a new development task"

Option 2: Traditional Docker Setup

Create a Dockerfile in your project root:

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/

# Create non-root user for security
RUN addgroup -g 1001 -S nodejs
RUN adduser -S mcp -u 1001
RUN chown -R mcp:nodejs /app
USER mcp

EXPOSE 3000

CMD ["node", "dist/index.js"]

Build and run the container:

# Build the image
docker build -t trello-mcp-server .

# Run with Docker MCP Toolkit (secure credential management)
docker run -d \
  --name trello-mcp \
  --env-file .env \
  -p 3000:3000 \
  trello-mcp-server

# Or use docker-compose.yml:

Create docker-compose.yml:

version: '3.8'
services:
  trello-mcp:
    build: .
    container_name: trello-mcp-server
    environment:
      - TRELLO_API_KEY=${TRELLO_API_KEY}
      - TRELLO_TOKEN=${TRELLO_TOKEN}
      - LOG_LEVEL=info
      - API_TIMEOUT=10000
    ports:
      - "3000:3000"
    restart: unless-stopped
    volumes:
      - ./logs:/app/logs
    networks:
      - mcp-network

networks:
  mcp-network:
    driver: bridge

Run with Docker Compose:

# Set environment variables in .env file, then:
docker-compose up -d

Benefits of Docker Desktop MCP Integration

Built-in Security: OAuth support and secure credential storage
One-Click Setup: Seamless integration with Claude, Cursor, VSCode, and other MCP clients
Cross-Platform: Consistent behavior across different architectures
Isolation: Memory, network, and disk isolation for production-ready security
Discovery: Access to 100+ verified MCP tools from Docker Hub's MCP Catalog

Cursor IDE Integration

In Cursor, you can set up the MCP server for AI-assisted development:

Install Cursor Extension (if available):
- Open Cursor IDE
- Go to Extensions marketplace
- Search for "MCP" or "Model Context Protocol"
Configure MCP Server: Create .cursor/mcp-config.json in your workspace:

{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/trello-mcp",
      "env": {
        "TRELLO_API_KEY": "your_api_key_here",
        "TRELLO_TOKEN": "your_token_here"
      }
    }
  }
}

Use with Cursor AI:
- Open Cursor's AI chat panel
- The Trello MCP tools should be available for context
- Ask questions like: "Show me my Trello boards and help me organize my tasks"

Windsurf IDE Integration

For Windsurf IDE integration:

Project Configuration: Create .windsurf/settings.json:

{
  "mcp": {
    "servers": {
      "trello": {
        "command": "node",
        "args": ["dist/index.js"],
        "cwd": "${workspaceFolder}",
        "env": {
          "TRELLO_API_KEY": "your_api_key_here",
          "TRELLO_TOKEN": "your_token_here"
        }
      }
    }
  },
  "ai": {
    "providers": {
      "claude": {
        "mcpServers": ["trello"]
      }
    }
  }
}

Workspace Setup: Add to your .windsurf/workspace.json:

{
  "name": "Trello MCP Development",
  "description": "Development workspace with Trello integration",
  "mcpServers": ["trello"],
  "tools": {
    "trello": {
      "enabled": true,
      "autoStart": true
    }
  }
}

Usage in Windsurf:
- The AI assistant will have access to Trello tools
- Use natural language commands in the AI chat
- Example: "Create a development task board and add cards for the current project features"

Development Container (DevContainer)

For consistent development environments, create .devcontainer/devcontainer.json:

{
  "name": "Trello MCP Development",
  "build": {
    "dockerfile": "../Dockerfile.dev"
  },
  "forwardPorts": [3000],
  "postCreateCommand": "npm install && npm run build",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-vscode.vscode-typescript-next",
        "esbenp.prettier-vscode",
        "bradlc.vscode-tailwindcss"
      ],
      "settings": {
        "mcp.servers": {
          "trello": {
            "command": "node",
            "args": ["dist/index.js"],
            "env": {
              "TRELLO_API_KEY": "${TRELLO_API_KEY}",
              "TRELLO_TOKEN": "${TRELLO_TOKEN}"
            }
          }
        }
      }
    }
  },
  "remoteEnv": {
    "TRELLO_API_KEY": "${localEnv:TRELLO_API_KEY}",
    "TRELLO_TOKEN": "${localEnv:TRELLO_TOKEN}"
  }
}

Create Dockerfile.dev:

FROM node:18

WORKDIR /workspace

# Install global tools
RUN npm install -g @modelcontextprotocol/inspector typescript

# Set up development environment
COPY package*.json ./
RUN npm install

# Copy source code
COPY . .

# Expose MCP server port
EXPOSE 3000

CMD ["npm", "run", "dev"]

Available Tools

Board Operations

list_boards - Get all boards accessible to the user
get_board - Get detailed information about a specific board
get_board_members - List members of a board

List Operations

get_lists - Get all lists in a board
create_list - Create a new list in a board
update_list - Update list properties (name, position)

Card Operations

get_cards - Get cards from a board or list
create_card - Create a new card
update_card - Update card properties (name, description, due date)
move_card - Move card to different list
delete_card - Delete a card
add_card_member - Add member to a card
remove_card_member - Remove member from a card

Label Operations

get_labels - Get available labels for a board
add_card_label - Add label to a card
remove_card_label - Remove label from a card

Checklist Operations

get_card_checklists - Get checklists on a card
create_checklist - Create a new checklist on a card
add_checklist_item - Add item to a checklist
update_checklist_item - Update checklist item (mark complete/incomplete)

Development

Project Structure

trello-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── trello-client.ts  # Trello API client
│   ├── tools/            # MCP tool implementations
│   │   ├── boards.ts
│   │   ├── lists.ts
│   │   ├── cards.ts
│   │   └── labels.ts
│   └── types/            # TypeScript type definitions
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Scripts

npm run build - Build TypeScript to JavaScript
npm run dev - Run in development mode with auto-reload
npm run start - Start the MCP server
npm run test - Run tests

Testing

# Install the MCP Inspector for testing
npm install -g @modelcontextprotocol/inspector

# Test the server
mcp-inspector node dist/index.js

Usage Examples

Once integrated with Claude Desktop, you can use natural language to interact with Trello:

"Show me all my Trello boards"
"Create a new card called 'Fix login bug' in the 'To Do' list of my Development board"
"Move the card 'Review PR #123' to the 'Done' list"
"Add the 'Priority' label to the card about the database migration"
"List all cards in my Personal board that are due this week"

Error Handling

The server includes comprehensive error handling for:

Network connectivity issues
Invalid API credentials
Rate limiting (429 errors)
Invalid board/list/card IDs
Permission errors

Security Notes

API credentials are passed via environment variables
No credentials are logged or stored in plain text
All API requests use HTTPS
Rate limiting is respected to avoid API abuse

Contributing

Fork the repository
Create a feature branch
Make your changes with proper TypeScript types
Add tests for new functionality
Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

Check the Trello API documentation: https://developer.atlassian.com/cloud/trello/rest
Review MCP documentation: https://modelcontextprotocol.io
Open an issue in this repository

Trello