trello-mcp

A small MCP server for Trello, built around the one thing the popular Trello MCP servers don't do: searching cards by custom field (e.g. find every card where the AI Ready field equals Claude kiosk).

It talks to the Trello REST API directly using your API key + token, returns compact results (no multi-hundred-KB board dumps), and resolves boards/cards by id, 8-char shortLink, URL, or name.

Tools

Tool	What it does
list_boards	All boards you can access — {id, name, shortLink, url}, nothing else.
list_custom_fields	Custom fields on a board + the allowed options for list-type fields. Use it to discover field names/values.
find_cards	Main tool. Find cards on a board, filtered by a custom field (fieldName + value, or values to match ANY of several), and/or listName, and/or label. Matching is case-insensitive (exact first, then substring). Omit value(s) to match "field is set".
get_card	Full content of one card: description, custom field values, checklists, attachments, comments, members, due date.
add_comment	Post a comment to a card (ask a clarifying question, or log progress).
set_custom_field	Set/clear a custom field on a card; createOption:true adds a new list option. Used to mark status (e.g. AI Ready → Done).
attach_file	Attach a file to a card — a local file by path or a remote file by url. Handy for posting a result file when finishing a task.

Setup

1. Get Trello credentials

Create a Power-Up at https://trello.com/power-ups/admin, grab the API Key from its API Key tab, then generate a Token:

https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&name=trello-mcp&key=YOUR_API_KEY

The Power-Up Secret is for OAuth and is NOT used here — only API Key + Token.

2. Register with Claude Code — zero clone, straight from GitHub

claude mcp add trello-cf --scope user \
  -e TRELLO_API_KEY=YOUR_KEY \
  -e TRELLO_TOKEN=YOUR_TOKEN \
  -- npx -y github:AxGrid/trello-mcp

--scope user makes it available in every project. npx installs and runs it on first launch — no git clone, no npm install. Restart Claude Code afterwards.

Or in claude_desktop_config.json / any MCP client:

{
  "mcpServers": {
    "trello-cf": {
      "command": "npx",
      "args": ["-y", "github:AxGrid/trello-mcp"],
      "env": { "TRELLO_API_KEY": "YOUR_KEY", "TRELLO_TOKEN": "YOUR_TOKEN" }
    }
  }
}

npx caches the GitHub package per resolved commit. To force a pull of the latest main, clear it once: npx clear-npx-cache (or rm -rf ~/.npm/_npx).

Local / dev install

git clone git@github.com:AxGrid/trello-mcp.git && cd trello-mcp && npm install
# then point the client at: node /abs/path/to/trello-mcp/server.mjs

Example

Find cards on the Stellar Kiosk board where AI Ready = Claude kiosk and let's solve them.

Claude calls find_cards({ board: "Stellar Kiosk", fieldName: "AI Ready", value: "Claude kiosk" }), then get_card(...) on the match.

Task lifecycle via a custom field

A single list-type field (here AI Ready) doubles as a status. Suggested values:

State	Value	How
Queued for AI	Claude kiosk, Claude Module, …	pick up with find_cards({fieldName:"AI Ready", values:["Claude kiosk","Claude Module"]})
Needs a human answer	Need response	set_custom_field(card, "AI Ready", "Need response", createOption:true) + add_comment(card, "question…")
Done	Done	optionally attach_file(card, path:"…/result.…"), then set_custom_field(card, "AI Ready", "Done", createOption:true)

Setting a new state moves the card out of the "queued" search automatically, since the field no longer equals a queued value. createOption:true is only needed the first time a value is introduced.

Self-test

Runs the core logic against your real account (read-only):

TRELLO_API_KEY=... TRELLO_TOKEN=... TEST_BOARD="Your Board" node selftest.mjs

Requirements

Node 18+ (uses the built-in global fetch). The only runtime dependency is @modelcontextprotocol/sdk.