MCP Server for Trello

Agent-native Model Context Protocol server for using Trello as a project-management backend for LLM agents.

The server exposes compact workflow tools first, with guarded raw Trello calls available only as escape hatches.

What's new in v0.5.0

• Atomic create_cards: each card spec accepts checklists: [{name, items: [...]}] and comments: ["...", ...]. Sub-resource failures emit partial_failure warnings (not errors) so envelope.ok stays True for the card-succeeded case.
• Idempotent ensure- operations*:
  • manage_lists(operation="ensure", name="Done") — case-insensitive match on open lists; creates if missing.
  • manage_labels(operation="ensure", name="Urgent", color="red") — same semantics for labels. Strict match: existing properties are NOT silently updated.
• Declarative manage_lists(operation="reorder", ordered_names=[...]) — listed-first, un-listed open lists trail in their existing order.
• manage_lists(operation="move_all_cards") safety: confirm=True required when source list has >1 card. dry_run=True previews card_count without requiring confirm.
• Hardening: classify_ref verifies /cards/<ref> before emitting wrong_tool; label_cards DELETE merges dict response into card (no more sparse receipts); get_card_context uses _board_cards(extra_fields=["desc"]) for description.

What's new in v0.3.0

• Input validation with field-level receipts (fields_summary.aliased/ignored/missing).
• Card label hydration: read and mutation responses now return labels: ["Feature"] (name strings) instead of empty arrays.
• Card shortLink resolution: RIQCFJBW-style 8-char references resolve everywhere a card is taken.
• New error codes: partial_resolution, wrong_tool, no_changes_requested, alias_collision.

Aliases accepted (move_cards): list, target_list, destination, move_to, list_name, target → to_list.

Aliases accepted (update_cards): description→desc, title→name, archived/archive/is_closed→closed, due_date→due, dueComplete→due_complete, idList→id_list, idMembers→id_members.

Aliases accepted (label_cards): labels/add_labels/label→add, remove_labels→remove.

Tool Surface

The revised MCP exposes 25 current tools. Prefer compact grouped tools before raw Trello calls.

Version helper:

• get_version

get_version returns the installed package version on demand. It is not part of normal board workflows.

Board discovery and read tools:

• open_board
• get_board_snapshot
• find_cards
• get_card_context
• get_board_activity

Card mutation tools:

• create_cards
• update_cards
• move_cards
• label_cards
• comment_on_card

Grouped project-management tools:

• manage_boards
• manage_cards
• manage_comments
• manage_checklists
• manage_attachments
• manage_custom_fields
• assign_members
• manage_lists
• manage_labels
• batch_get_compact

Raw guarded escape hatches:

• trello_get
• trello_post
• trello_put
• trello_delete

Raw tools are for cases the compact surface cannot express. They reject unsafe endpoints, credential-bearing URLs, and unconfirmed deletes.

Response Shape

Tools return compact dict envelopes:

{
  "ok": true,
  "tool": "open_board",
  "board": {"id": "...", "name": "...", "url": "..."},
  "result": {},
  "warnings": [],
  "errors": []
}

Errors and warnings use stable machine-readable codes so agents can recover or retry safely. Mutation tools return compact receipts plus a top-level verified_by source: "trello_mutation_response" for real writes, "trello_board_snapshot" for unchanged items, and "dry_run" for previews. When the source is a real Trello write response, call read tools only when extra fields such as description, checklists, or activity are needed.

Board Maps

open_board refreshes a local board map so agents can resolve board-local list and label aliases without rediscovering IDs each turn.

Default storage:

~/.config/mcp-server-trello/boards

Override storage with:

TRELLO_MCP_BOARD_MAP_DIR=/path/to/boards

Board maps store board/list/label metadata and aliases. They do not store card contents, comments, or credentials.

Example Workflows

Open a board:

open_board(name_or_id="Suitepath")

Create cards in bulk:

create_cards(board_id_or_name="Suitepath", list="TODO", cards=[{"name": "Draft release notes"}])

Label cards in bulk:

label_cards(board_id_or_name="Suitepath", card_refs=["Draft release notes"], add=["Feature"])

Inspect recent activity:

get_board_activity(board_id_or_name="Suitepath", limit=10)

Run a compact batch read:

batch_get_compact(urls=["/boards/board_id/cards", "/boards/board_id/labels"])

Installation

TypeScript/Bun package usage:

bunx @khgs2411/mcp-server-trello

Python package usage remains supported until a separate deprecation decision:

uvx mcp-server-trello

Required runtime environment:

• TRELLO_API_KEY
• TRELLO_API_TOKEN

Deployment

See DEPLOYMENT.md for the npm and PyPI release flows.