Trello MCP Server

Connect AI assistants to Trello via the Model Context Protocol.

Boards, lists, cards, and comments — exposed as MCP tools, with safe read-only defaults.

---

✨ Features

• 🔍 Full read access — boards, lists, cards, comments, and member info
• ✏️ Optional write access — create, update, and move cards; add comments (opt-in)
• 🔒 Read-only by default — write tools are never registered, and the HTTP client blocks non-GET requests as defense-in-depth
• ⏱️ Trello-aware rate limiting — conservative request budgets, 429 retry with exponential backoff
• 🚀 Single static binary — no runtime dependencies; stdio transport
• ✅ Startup credential checks — verifies auth and token scope/expiry before serving

📋 Prerequisites

• Go 1.25+ (1.26.4 recommended)
• A Trello account
• A Trello API key and authorization token (see below)

🔑 Getting Trello Credentials

1. API key

1. Go to trello.com/power-ups/admin and create a new Power-Up (or use an existing one).
2. Open the API Key tab and copy your API Key.

Note

The classic trello.com/app-key page is the legacy method. Power-Up administration is the current recommended path.

2. Authorization token

Open one of these URLs, replacing {YourAPIKey} with your key:

Read-only (recommended):

https://trello.com/1/authorize?expiration=30days&scope=read&response_type=token&key={YourAPIKey}

Read + write (if you need to create or modify cards):

https://trello.com/1/authorize?expiration=30days&scope=read,write&response_type=token&key={YourAPIKey}

Caution

The token grants full account access within its scope. Treat it like a password — never share it, commit it, or log it.

🚀 Quick Start

Build

git clone https://github.com/treeol/mcptrello.git
cd mcptrello
go build -o trello-mcp ./cmd/trello-mcp

Configure your MCP client

Add the server to your MCP client configuration (e.g. Claude Desktop):

{
  "mcpServers": {
    "trello": {
      "command": "/path/to/trello-mcp",
      "env": {
        "TRELLO_API_KEY": "your-api-key",
        "TRELLO_API_TOKEN": "your-token",
        "TRELLO_READ_ONLY": "true"
      }
    }
  }
}

That's it — ask your assistant to list your boards and start exploring.

⚙️ Configuration

Variable	Required	Default	Description
TRELLO_API_KEY	✅	—	Trello API key
TRELLO_API_TOKEN	✅	—	Trello authorization token
TRELLO_READ_ONLY	—	true	Set to false to enable write tools

Read-only mode

The server starts in read-only mode unless explicitly disabled. In this mode:

• Only read tools are registered
• Write tools are not available at all
• The HTTP client blocks PUT/POST/DELETE as a second layer of defense

The flag is strict: only the exact string "false" enables writes. Any other value — empty, "0", "no", "FALSE" — keeps the server read-only.

🛠️ Tools

Read tools (always available)

Tool	Description	Required parameters
get_me	Authenticated member info	—
get_boards	List all boards	—
get_board	Get a single board	board_id
get_lists	Lists on a board	board_id
get_cards	Cards in a list	list_id
get_card	Get a single card	card_id
get_comments	Comments on a card	card_id

Write tools (require TRELLO_READ_ONLY=false)

Tool	Description	Required parameters
create_card	Create a card	id_list, name
update_card	Update card fields	card_id
move_card	Move card to another list	card_id, id_list
add_comment	Comment on a card	card_id, text

⏱️ Rate Limiting

Built-in limiters track Trello's API budgets:

Scope	Budget	Basis
API key	~270 req / 10 s	90% of Trello's 300/10 s ceiling
Token	~90 req / 10 s	90% of Trello's 100/10 s ceiling — the binding constraint
Special routes (/members, /search)	~100 req / 900 s	Trello's per-route limits

These are a conservative floor: the server reads Trello's x-rate-limit-* headers as the authoritative source, and retries 429 responses automatically with exponential backoff (up to 3 attempts).

Important

Rate limits are per API key, account-wide. Multiple instances sharing one key share one budget — use one key per deployment.

📅 Token Expiry

Tokens generated with expiration=30days stop working after 30 days (401 unauthorized). Re-authorize with the same URL to mint a new one. For unattended deployments, expiration=never is possible — with the documented security trade-off.

🏗️ Architecture

cmd/trello-mcp/main.go        Entry point, server setup, signal handling
internal/
├── config/config.go          Environment variable loading
├── trello/
│   ├── client.go             Pure HTTP Trello API client (no MCP types)
│   ├── types.go              Trello API response structs
│   └── ratelimit.go          Rate-limited RoundTripper with 429 retry
└── tools/                    MCP tool definitions by domain
    ├── register.go           Tool registration (writes gated by read-only)
    ├── boards.go             get_boards, get_board
    ├── lists.go              get_lists
    ├── cards.go              get_cards, get_card, create_card, update_card, move_card
    ├── comments.go           get_comments, add_comment
    └── members.go            get_me

Clean layering: internal/trello knows nothing about MCP, and internal/tools knows nothing about HTTP.

🔧 Development

# Build
go build -o trello-mcp ./cmd/trello-mcp

# Test
go test ./... -race -count=1

# Lint
go vet ./...

# Cross-compile (static binaries)
GOOS=linux  GOARCH=amd64 go build -o trello-mcp-linux  ./cmd/trello-mcp
GOOS=darwin GOARCH=arm64 go build -o trello-mcp-darwin ./cmd/trello-mcp

🔐 Security

• Credentials travel in the Authorization header — never in URLs or proxy logs
• Credentials are never logged or included in error messages
• Read-only mode is enforced twice: write tools aren't registered, and the HTTP client blocks non-GET requests
• Token scope is checked at startup — the server warns on mismatches (write-capable token in read-only mode, and vice versa)
• For least privilege, mint a scope=read token when running read-only
• Card and board text fetched from Trello flows into tool outputs — an inherent prompt-injection surface for any MCP tool server. Be thoughtful about which boards you expose.

🧯 Troubleshooting

Symptom	Likely cause
TRELLO_API_KEY and TRELLO_API_TOKEN must be set	Missing environment variables
unauthorized — token is invalid or revoked	Token expired (30-day tokens) or revoked
rate limited by Trello	API budget exhausted — wait and retry
response too large	Response exceeds 1 MB — use field selection
resource not found	Invalid board, list, or card ID

📄 License

Distributed under the MIT License.

---

Trello is a trademark of Atlassian. This project is not affiliated with, endorsed by, or sponsored by Atlassian.