io.github.BillNobill/trello-mcp-server

🚀 Trello MCP Server: AI-Powered Project Management

Transform your Trello boards into a living workspace for AI agents. This Model Context Protocol (MCP) server allows LLMs (like Gemini, Claude, and GPT-4) to see, organize, and manage your projects with natural language.

🔍 Overview

This project bridges the gap between AI and your Trello workflow. Instead of manually moving cards, you can tell your AI: "Move all 'To Do' cards with the 'Urgent' label to 'In Progress' and assign them to me."

Global Usage: You can save this project anywhere on your computer. Once registered, your AI will be able to start the server automatically whenever needed—no manual terminal execution required.

📋 Prerequisites

• Node.js (v20.0.0 or higher recommended) - Download here
• Git - Download here
• Trello API Key and Token: Get them here

🛠️ Quick Start

1. Installation & Build

# Clone the repository
git clone https://github.com/BillNobill/trello-mcp-server.git

# Install dependencies and build
npm install
npm run build

2. Configuration

Create a .env file in the project root (use .env.example as a template):

TRELLO_API_KEY=your_api_key
TRELLO_TOKEN=your_token
TRELLO_BASE_URL=https://api.trello.com/1

3. Register with your AI client

Claude Code (Recommended)

claude mcp add --scope user trello node "C:\FULL_PATH\TO\trello-mcp-server\dist\index.js"

Env vars are read from the .env file or can be passed inline with -e KEY=VALUE flags.

VS Code (GitHub Copilot / Claude extension)

Add to your user settings.json (Ctrl+Shift+P → Open User Settings JSON):

{
  "mcp": {
    "servers": {
      "trello": {
        "command": "node",
        "args": ["C:\\FULL_PATH\\TO\\trello-mcp-server\\dist\\index.js"],
        "env": {
          "TRELLO_API_KEY": "your_api_key",
          "TRELLO_TOKEN": "your_token",
          "TRELLO_BASE_URL": "https://api.trello.com/1"
        }
      }
    }
  }
}

Cursor

Add to %USERPROFILE%\.cursor\mcp.json:

{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["C:\\FULL_PATH\\TO\\trello-mcp-server\\dist\\index.js"],
      "env": {
        "TRELLO_API_KEY": "your_api_key",
        "TRELLO_TOKEN": "your_token",
        "TRELLO_BASE_URL": "https://api.trello.com/1"
      }
    }
  }
}

[!IMPORTANT] Always use the absolute path to dist/index.js in the configuration above.

⚡ Available Tools

Your AI agent will automatically "learn" these advanced capabilities:

📋 Board & List Management

• list_boards: List all your Trello boards.
• read_board: Deep dive into lists, cards, labels, and members.
• get_lists_on_board: Fetch only column names and IDs.
• create_list / update_list: Manage board columns and their ordering (pos).
• archive_list: Cleanup board structure.
• get_board_labels / get_board_members: Fetch IDs for precise automation.
• create_label / update_label: Manage board labels (names and colors).

🗂️ Card Operations (Granular & Optimized)

• get_cards_in_list: Fetch cards for a specific column.
• get_card_details: Deep dive into comments, attachments, and checklists for a single card.
• search_cards: Perform fast text-based searches across the entire board.
• create_card / update_card: Create or modify tasks (name, desc, dates, labels, and pos).
• move_card: Change task status across lists (supports pos).
• move_all_cards: Bulk Action to move all cards from one list to another.
• archive_card: Cleanup completed work.

✅ Checklist Management (Granular & Fluid)

• add_checklist: Create a new checklist header on a card.
• update_checklist: Rename or reorder an existing checklist header.
• delete_checklist: Remove a checklist entirely.
• create_checkitem: Add a new item to an existing checklist.
• update_checkitem: Update items (rename, mark as complete/incomplete, or reorder).
• delete_checkitem: Remove a specific item from a checklist.

📁 Files & Attachments

• add_attachment: Attach URL-based links to cards.
• upload_file: Upload real files (PDFs, scripts, reports) directly from your computer to a card.

🛠️ Professional Features

• set_custom_field: Set values for Custom Fields (e.g., "Estimate", "Project ID"). Note: Requires Custom Fields Power-Up enabled on the board.
• assign_member: Assign teammates to tasks.
• add_comment: Discuss tasks directly through the AI.

[!TIP] Reordering (the pos parameter):
Use 'top', 'bottom', or a positive number (e.g., 1) to precisely reorder cards, lists, checklists, and items.

🛠️ Troubleshooting

[!WARNING] Server shows as "Disconnected"?

1. Empty Command: Check your client's MCP config and confirm "command": "node" and the absolute path to dist/index.js are correct.
2. Environment Variables: Run node dist/index.js manually in the terminal. If it fails, your .env is likely missing from the root folder.
3. SDK Compatibility: This project uses @modelcontextprotocol/sdk v1.29.0. If you experience protocol errors, run npm install to ensure you have the correct version.
4. Claude Code: Run /mcp inside a Claude Code session to see the server status and any error output.

🐳 Docker Support

[!TIP] Docker is perfect for keeping your local environment clean.

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

# Run
docker run --rm -i --env-file .env trello-mcp-server

🤝 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.

Created by [Luiz Feltrin]
Show some love! Give this repository a ⭐️ if it helped you!