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 
cd trello-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Authentication Setup

1. Get Trello API Credentials:

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:

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):

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:

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:

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