trello-mcp

A Model Context Protocol server for Trello. It gives an AI assistant read and write access to your Trello boards: list boards and cards, read a card with its comments and checklists, search, create and update cards, move them between lists, comment, label, and archive.

It runs over stdio with your own free Trello API key and token, so it works with Claude Code, Claude Desktop, Codex CLI, Cursor, and any other MCP client.

There is no delete tool. See Safety.

Requirements

• Node.js 20 or newer
• A Trello account (free is fine)

Get your credentials

Trello needs two values: an API key and a token. Both are personal secrets.

1. Go to https://trello.com/power-ups/admin and create a Power-Up. Name and workspace do not matter; this is just how Trello hands out API keys these days.
2. Open the Power-Up's API key tab. The value in the "API key" field is your TRELLO_API_KEY.
3. In the paragraph to the right of that field ("… you can manually generate a Token"), click the Token link. Approve the access request. The long string Trello then shows you is your TRELLO_TOKEN.

Ignore the Secret field and Allowed origins on that page — they belong to Trello's OAuth flow, which this server does not use. The token, not the secret, is what pairs with your API key here.

The token inherits your own Trello permissions: the server can see and change exactly what you can, and nothing more. You can revoke it any time from https://trello.com/my/account under "Applications".

Quick start

TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token npx -y github:rilolabs/trello-mcp

It will print trello-mcp <version> ready on stdio to stderr and then wait for MCP traffic on stdin. That is the correct behaviour — it is meant to be launched by an MCP client, not used by hand. Started without credentials, it exits immediately with instructions.

The github: form fetches this repository and builds it on your machine; the first run takes a minute, later runs use npx's cache. It is not published to the npm registry.

Configuration

Claude Code

claude mcp add trello \
  -e TRELLO_API_KEY=your-key \
  -e TRELLO_TOKEN=your-token \
  -- npx -y github:rilolabs/trello-mcp

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) and add:

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "github:rilolabs/trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

Restart Claude Desktop afterwards.

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.trello]
command = "npx"
args = ["-y", "github:rilolabs/trello-mcp"]
env = { TRELLO_API_KEY = "your-key", TRELLO_TOKEN = "your-token" }

Any other stdio MCP client

Cursor (.cursor/mcp.json), Windsurf, Zed, and most other clients take the same generic shape:

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "github:rilolabs/trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

Transport is stdio; there is no HTTP mode.

Tools

Ids flow downward: list_boards gives you board ids, get_lists gives list ids, get_cards and search_cards give card ids, get_labels gives label ids.

Tool	Type	Parameters	What it does
list_boards	read	—	Every board the token can see: id, name, url, closed.
get_lists	read	board_id	Open lists on a board, in board order.
get_cards	read	board_id, list_id?, label?, include_archived? (false), limit? (50)	Cards on a board, optionally filtered to one list or one label name. Returns trimmed summaries.
get_card	read	card_id	One card in full: description, labels, due, members, checklist done/total, recent comments.
search_cards	read	query, board_id?	Trello search, including operators like due:week or label:urgent. Up to 25 results.
get_labels	read	board_id	Board labels with id, name and colour.
get_board_activity	read	board_id, days? (7)	Recent actions on a board, one readable line each.
create_card	write	list_id, name, desc?, due?, label_ids?	Creates a card at the bottom of a list.
update_card	write	card_id, name?, desc?, due?	Updates title, description, or due date. due: null clears the due date.
move_card	write	card_id, list_id, position? (top/bottom)	Moves a card to another list.
add_comment	write	card_id, text	Posts a comment as the authenticated user.
add_label	write	card_id, label_id	Attaches an existing board label to a card.
remove_label	write	card_id, label_id	Detaches a label from a card. The label stays on the board.
archive_card	write	card_id	Archives a card. Reversible.
unarchive_card	write	card_id	Restores an archived card to its list.

Results come back as compact JSON with the useful fields selected, not as raw Trello API objects.

Safety

No delete tool, by design. Trello's DELETE /cards/{id} is permanent. There is no trash and no undo, and the card's comments, checklists, and history are destroyed with it. An assistant that can delete cards can wipe out work irrecoverably on a single wrong id. archive_card is the reversible equivalent and covers every legitimate "get this off the board" case, so this server ships no card deletion and will not be adding one.

Credentials stay in environment variables. TRELLO_API_KEY and TRELLO_TOKEN are read from the environment at startup and never written to disk, never echoed to stdout, and never included in a tool result.

Trello authenticates by putting the key and token in the URL query string, which makes any raw URL in an error message a credential leak. Every error path in this server is routed through a redactor that strips key= and token= values and scrubs the secret strings themselves before anything is thrown, logged, or returned. Diagnostics go to stderr; stdout carries protocol traffic only.

Scope. The token has your Trello permissions, no more. If you want to limit exposure, use a Trello account that is only a member of the boards you want reachable, and revoke the token from https://trello.com/my/account when you are done.

Development

npm install
npm run build     # compile to dist/
npm run dev       # run from source with tsx

Smoke-test the wire protocol without touching Trello:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | TRELLO_API_KEY=x TRELLO_TOKEN=x node dist/index.js

Layout:

src/index.ts        entry point: env check, server wiring, stdio transport
src/trello.ts       Trello REST client + credential redaction
src/format.ts       result formatting and error mapping
src/tools/read.ts   read-only tools
src/tools/write.ts  write tools

License

MIT © Rilo Labs