Skip to main content
Glama

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)

Related MCP server: Trello MCP Server

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

Available Tools

15 tools
add_commentComment on a cardA

Post a comment on a card as the authenticated Trello user. text is Markdown. Comments are the right place for context and decisions — they are preserved in the card history.

Inputs: text (required), card_id (required).

add_labelAdd a label to a cardA

Attach an existing board label to a card. label_id comes from get_labels — label names are not accepted. Adding a label the card already has is a no-op error from Trello, so check get_card first if unsure.

Inputs: card_id (required), label_id (required).

archive_cardArchive a cardA

Archive a card — Trello's reversible "remove". The card leaves the board view but keeps its comments, checklists and history, and unarchive_card brings it back. This server has no delete tool on purpose: Trello deletion is permanent and unrecoverable, so archiving is always the correct move.

Inputs: card_id (required).

create_cardCreate a cardA

Create a card at the bottom of a list. list_id comes from get_lists. desc is Markdown. due is an ISO 8601 date or datetime (e.g. 2026-08-20 or 2026-08-20T17:00:00Z). label_ids are label ids from get_labels — names will not work. Returns the created card including its id and url.

Inputs: name (required), list_id (required), due, desc, +1 more.

get_board_activityGet recent board activityA
Read-only

Recent activity on a board — cards created, moved, archived, commented on — newest first, as one readable line per action plus the raw action type. days defaults to 7. Good for "what changed this week" without diffing card state. board_id comes from list_boards.

Inputs: board_id (required), days.

get_cardGet one card in fullA
Read-only

Get a single card with everything worth reading: full description, labels, due date, assigned members, a per-checklist done/total summary, and the most recent comments. card_id comes from get_cards, search_cards or a Trello card URL.

Inputs: card_id (required).

get_cardsGet cards on a boardA
Read-only

Get cards on a board, optionally narrowed to one list or one label. board_id comes from list_boards; list_id (optional) comes from get_lists; label (optional) is a label NAME as shown by get_labels, matched case-insensitively. include_archived defaults to false, limit defaults to 50. Each card comes back trimmed: id, name, list, labels, due, url and a shortened description — call get_card for the full card with comments and checklists.

Inputs: board_id (required), label, limit, list_id, +1 more.

get_labelsGet board labelsA
Read-only

List the labels defined on a board, with id, name and colour. Use this before create_card or add_label to turn a human label name into the label id those tools require. board_id comes from list_boards.

Inputs: board_id (required).

get_listsGet lists on a boardA
Read-only

Get the open (non-archived) lists on a Trello board, in board order. board_id comes from list_boards. Returns id, name and position — the list ids are what create_card and move_card need.

Inputs: board_id (required).

list_boardsList Trello boardsA
Read-only

List every Trello board the configured token can see, including archived (closed) ones. Returns id, name, url and closed for each. Start here: the board ids returned feed get_lists, get_cards, get_labels and get_board_activity.

Inputs: no named parameters.

move_cardMove a card to another listA

Move a card to a different list on the same board. list_id comes from get_lists. position is optional: "top" or "bottom" (default "bottom") within the destination list.

Inputs: card_id (required), list_id (required), position.

remove_labelRemove a label from a cardA

Detach a label from a card. This removes the label from that one card only — the label itself stays on the board. label_id comes from get_labels or from get_card.

Inputs: card_id (required), label_id (required).

search_cardsSearch cardsA
Read-only

Search Trello cards with Trello's own search syntax (plain words, or operators like "due:week", "label:urgent", "@me", "is:open"). Pass board_id to scope the search to one board, otherwise it covers every board the token can see. Returns up to 25 trimmed card summaries.

Inputs: query (required), board_id.

unarchive_cardUnarchive a cardA

Restore an archived card to its list. Find archived cards with get_cards using include_archived: true, or with search_cards.

Inputs: card_id (required).

update_cardUpdate a cardA

Update a card's title, description or due date. Only the fields you pass are changed; omitted fields are left alone. Pass due as an ISO 8601 date to set it, or null to clear it. To move a card between lists use move_card; to archive it use archive_card.

Inputs: card_id (required), due, desc, name.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct action-resource pair: card CRUD (create/get/update/move/archive/unarchive), comments, labels, boards, lists, and search. Even similar tools like get_cards vs get_card vs search_cards have clear differences in scope and return shape.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern: get_*, create_card, update_card, move_card, archive_card, unarchive_card, add_comment, add_label, remove_label, list_boards. There are no mixed styles or vague verbs like 'process' or 'do_thing'.

    Tool Count5/5

    15 tools is at the upper end of the ideal range but well justified by the breadth of Trello operations covered: boards, lists, cards, labels, comments, search, and activity. Each tool serves a distinct purpose with no redundancy.

    Completeness4/5

    The card lifecycle is fully covered (create, read, update, archive/unarchive instead of permanent delete), plus labels, comments, search, and board activity. Minor gaps exist: no board or list creation/update/delete, but the server is clearly card-centric and archiving is intentionally used as a safe deletion alternative.

    Related MCP Connectors

    Related MCP Servers