io.github.BillNobill/trello-mcp-server

Trello Model Context Protocol (MCP) Server for AI Agents
Open source Open in the app JSON README (API)
About

Trello Model Context Protocol (MCP) Server for AI Agents
Details

Kind: MCP servers
Topic: AI, RAG & memory
Publisher: billnobill
Origin: official
Category: ferramentas
Transport: local
Version: 1.1.0
Stars: 2
Last push: 2026-08-19T23:21:10Z
Repository state: ativo
Language: TypeScript
License: MIT
Added: 2026-08-29 03:01:42
Updated: 2026-08-29 03:01:42
Origin id: io.github.BillNobill/trello-mcp-server
README

# 🚀 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](https://nodejs.org/)
- **Git** - [Download here](https://git-scm.com/)
- **Trello API Key and Token**: [Get them here](https://trello.com/app-key)

---

## 🛠️ Quick Start

### 1. Installation & Build
```powershell
# 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):
```env
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)
```powershell
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*):
```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`:
```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.

```powershell
# 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!*
io.github.BillNobill/trello-mcp-server

About

Details

README

More
