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

1. Clone the repository:

git clone <repository-url>
cd trello-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Authentication Setup

1. 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

2. 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)

1. 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

2. Publish to Docker Hub's MCP Catalog:

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

3. Configure in Claude Desktop with Docker MCP:

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

4. 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:

1. Install Cursor Extension (if available):

   • Open Cursor IDE
   • Go to Extensions marketplace
   • Search for "MCP" or "Model Context Protocol"

2. 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"
      }
    }
  }
}

3. 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:

1. 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"]
      }
    }
  }
}

2. 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
    }
  }
}

3. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes with proper TypeScript types
4. Add tests for new functionality
5. 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