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.7

• Download every uploaded attachment on a card: manage_attachments(operation="download_all", destination_path="/absolute/output/directory", confirm=true) creates the destination directory when needed and downloads all Trello-uploaded files there using authenticated attachment requests.
• Downloads stream through temporary files, verify declared byte counts, publish atomically with safe original filenames, and refuse to overwrite existing files. Linked URL attachments are reported as skipped and are never fetched with Trello credentials.
• The attachment workflow intentionally does not expose a single-attachment download operation.

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"])

Download every uploaded file attachment on a card:

manage_attachments(
  board_id_or_name="Suitepath",
  card="Card name or URL",
  operation="download_all",
  destination_path="/absolute/path/to/downloads",
  confirm=true
)

destination_path must be an absolute directory path. The directory is created when needed. Existing files are never overwritten. Trello-uploaded files are downloaded; linked URL attachments are returned in skipped. Set dry_run=true to preview the output paths without creating the directory or downloading files. max_total_bytes defaults to 1 GiB and can be raised explicitly when a card's declared attachment size is larger.

Installation

bunx @khgs2411/mcp-server-trello

Required runtime environment:

• TRELLO_API_KEY
• TRELLO_API_TOKEN

Deployment

See DEPLOYMENT.md for the npm release flow.