🚀 Advanced Trello MCP Server

> Enhanced Model Context Protocol Server for Trello integration with Cursor AI

> Production-hardened API layer, batch tools, and attachment downloads

TypeScript

Trello API

MCP Protocol

License

📋 Overview

This is an enhanced version of the Trello MCP Server that provides comprehensive integration between Trello and Cursor AI (and similar MCP clients). It includes ~35 tools across boards, lists, cards, labels, and actions, plus a reliable HTTP layer suited to heavy or sequential API use.

✨ Features

🛡️ Reliability (production-tested)

All Trello calls (MCP resources and tools) go through a shared client in `src/utils/api.ts`:

• HTTPS keep-alive — reuses TLS connections (helps avoid CloudFront / CDN connection churn on burst traffic)
• `fetchWithRetry` — ~60s timeout, exponential backoff with jitter (up to 7 attempts), retries on network errors and 5xx
• Sliding-window rate limit — ~80 requests / 10s (mutex-protected)
• 429 handling — respects `Retry-After` when present

🎯 API coverage (current)

🔧 Other

• TypeScript + Zod validation on tool inputs
• Batch operations — fewer round-trips for agents (`create-cards`, `move-cards`, `archive-cards`, `add-comments`, etc.)
• Attachment pipeline — list metadata + optional download to disk (see below)

🚀 Quick Start

Prerequisites

• Node.js 18+
• Trello API Key and Token
• Cursor (or any MCP client)

Installation

1. Clone the repository

git clone https://github.com/adriangrahldev/advanced-trello-mcp-server.git
   cd advanced-trello-mcp-server

2. Install dependencies

npm install

3. Build the project

npm run build

4. Configure environment variables

export TRELLO_API_KEY="your_api_key"
   export TRELLO_API_TOKEN="your_api_token"

5. Configure Cursor MCP

Add to your `~/.cursor/mcp.json` (paths adjusted for your machine):

🛠️ Available Tools

📋 Lists (10)

• `get-lists` — Lists on a board
• `create-list` / `update-list` / `archive-list`
• `move-list-to-board`
• `get-list-actions` / `get-list-board` / `get-list-cards`
• `archive-all-cards-in-list` / `move-all-cards-in-list`

🎯 Cards (12)

• `create-card` — Optional `due` and `start` (ISO 8601)
• `create-cards` — Batch create; each card may include `due` / `start`
• `update-card` — Name and/or description
• `move-card` / `move-cards`
• `add-comment` / `add-comments` (batch comments on multiple cards)
• `get-tickets-by-list`
• `archive-card` / `archive-cards`
• `get-card-attachments` — Metadata + `commentContext` (e.g. screenshots on comments)
• `download-card-attachments` — Downloads files to a folder (numbered files + `_manifest.json`). File URLs often require OAuth-style `Authorization` header (not query-string key/token); this tool handles that.

🏷️ Labels (8)

• `create-label` / `create-labels`
• `add-label` / `add-labels`
• `get-label` / `update-label` / `delete-label` / `update-label-field`

📊 Actions (4)

• `get-action` — With optional display/entities/member params
• `update-action` / `delete-action`
• `get-action-reactions`

🏢 Boards (1)

• `get-boards`

❓ Why is an old Pull Request still “open” on GitHub?

GitHub marks a PR as Merged only when you merge that PR (green “Merge pull request” button), or when the PR branch is merged in a way GitHub links to the PR.

If you cherry-picked, copied files, or merged locally into `main` and pushed `main`, the code is on the repo but the PR stays open until you:

1. Close the PR manually — add a comment such as: *“Landed on `main` via commit ** — thanks!”*

2. Or use GitHub’s merge flow next time so the PR closes automatically.

Conflicts on fork-based PRs are normal; resolving on your machine and pushing `main` is fine — just close the PR afterward so contributors know it’s done.

📈 Roadmap

Broader Trello API coverage (checklists, members, webhooks, search, etc.) is planned. PRs welcome.

🔧 Development

Project structure

advanced-trello-mcp-server/
├── src/
│   ├── index.ts
│   ├── tools/       # boards, lists, cards, labels, actions
│   ├── types/
│   └── utils/       # api.ts — fetchWithRetry, keep-alive, rate limit
├── build/
├── scripts/build.js
├── package.json
└── README.md

Building

npm run build    # TypeScript + shebang on build/index.js
npm run compile  # tsc only

Cross-platform build (Windows / macOS / Linux): compiles TS, adds `#!/usr/bin/env node`, sets execute bit on Unix.

🤝 Contributing

1. Fork the repository

2. Branch (`git checkout -b feature/...`)

3. Commit (Conventional Commits encouraged)

4. Open a Pull Request

If the maintainer merges your work outside the GitHub PR UI, they may close the PR with a link to the landing commit — that does not mean your contribution wasn’t accepted.

📚 API documentation

Tools follow the Trello REST API. Inputs are validated with Zod.

🐛 Troubleshooting

📄 License

MIT — see LICENSE.

🙏 Acknowledgments

• Original Trello MCP Server — yairhaimo/trello-mcp-server
• Trello API · MCP · Cursor

Built with ❤️ for the Cursor AI community