Trello MCP tools

Find boards, manage cards, edit checklists and handle attachments through 48 Model Context Protocol tools.

With credentials configured, all 48 tools are available by default. Read-only mode hides 29 mutation/transfer tools, leaving 19 reads and local-selection tools eligible. Without credentials, only server_health is registered with a setup hint.

Use TRELLO_TOOLS to select comma-separated tool names or prefix groups. Selectors form a union, so card includes both card-member tools. Unknown selectors fail startup; read-only filtering still applies to explicitly selected writes. Include server or server_health for diagnostics.

Workspaces

workspace_findRead: Find allowed workspaces by name.Parameters: nameFilter.Required: none (defaults apply).
workspace_useLocal selection: Set the active workspace and clear the active board.Parameters: workspaceId.Required: workspaceId

Boards

board_findRead: Find accessible open boards, including guest boards, optionally narrowed by workspace.Parameters: workspaceId, nameFilter.Required: none (defaults apply).
board_useLocal selection: Set an authorized board as the local default.Parameters: boardId.Required: boardId
board_getRead: Get curated summary or full board details.Parameters: boardId, detail.Required: none (defaults apply).
board_activityRead: Page board actions, newest first, with an upstream action-type filter (default all) and since/before cursors.Parameters: boardId, limit, since, before, filter.Required: none (defaults apply).
board_createMutation / transfer: Create a board in an authorized workspace.Parameters: workspaceId, name, desc, defaultLists.Required: name

Lists

list_findRead: Find open lists on a board.Parameters: boardId, nameFilter.Required: none (defaults apply).
list_createMutation / transfer: Create a list with optional position.Parameters: boardId, name, pos.Required: name
list_updateMutation / transfer: Rename, reorder, move with idBoard, or reopen with closed: false.Parameters: boardId, listId, name, pos, idBoard, closed.Required: listId
list_archiveMutation / transfer: Archive a list.Parameters: boardId, listId.Required: listId
list_watchMutation / transfer: Subscribe or unsubscribe with subscribed (default true).Parameters: boardId, listId, subscribed.Required: listId

Cards and card members

card_findRead: Find open board, list or assigned cards, with no archive selector; names are filtered before paging a local snapshot. Summary detail omits url; includeDesc: false also omits description previews.Parameters: boardId, listId, mine, nameFilter, detail, limit, before, includeDesc.Required: none (defaults apply).
card_getRead: Get a card with optional full detail, extras or markdown.Parameters: boardId, cardId, detail, view, extraFields.Required: cardId
card_historyRead: Page card actions with an upstream action-type filter.Parameters: boardId, cardId, limit, before, since, filter.Required: cardId
card_createMutation / transfer: Create a card in a verified list, with optional labels, members and checklist.Parameters: boardId, listId, name, desc, due, start, pos, idMembers, idLabels, checklist.Required: listId, name
card_create_batchMutation / transfer: Preflight ids, then create 1-100 cards with optional checklists and per-card results.Parameters: boardId, listId, cards.Required: listId, cards
card_updateMutation / transfer: Update details, labels, members, dates, archive state or position.Parameters: boardId, cardId, name, desc, due, start, dueComplete, closed, pos, idMembers, idLabels.Required: cardId
card_archiveMutation / transfer: Archive a card.Parameters: boardId, cardId.Required: cardId
card_watchMutation / transfer: Subscribe or unsubscribe with subscribed (default true).Parameters: boardId, cardId, subscribed.Required: cardId
card_moveMutation / transfer: Move to listId, resolving and checking both boards.Parameters: boardId, cardId, listId, idBoard, pos.Required: cardId, listId
card_copyMutation / transfer: Copy to listId, resolving and checking both boards.Parameters: boardId, cardId, listId, idBoard, name, pos.Required: cardId, listId
card_member_addMutation / transfer: Assign a verified board member to a card.Parameters: boardId, cardId, memberId.Required: cardId, memberId
card_member_removeMutation / transfer: Remove a verified board member from a card.Parameters: boardId, cardId, memberId.Required: cardId, memberId

Comments

comment_findRead: Page comments on a card, newest first.Parameters: boardId, cardId, limit, before, since.Required: cardId
comment_createMutation / transfer: Add a comment.Parameters: boardId, cardId, text.Required: cardId, text
comment_updateMutation / transfer: Edit a verified card comment by commentId.Parameters: boardId, cardId, commentId, text.Required: cardId, commentId, text
comment_deleteMutation / transfer: Delete a verified card comment.Parameters: boardId, cardId, commentId.Required: cardId, commentId

Checklists and items

checklist_itemsRead: Get items from an authorized checklist.Parameters: boardId, checklistId.Required: checklistId
checklist_getRead: Find a card checklist by exact name, default Acceptance Criteria. A miss lists up to 20 available names.Parameters: boardId, cardId, name.Required: cardId
checklist_createMutation / transfer: Create a card checklist.Parameters: boardId, cardId, name, pos.Required: cardId, name
checklist_copyMutation / transfer: Copy checklistId to cardId, checking both boards.Parameters: boardId, cardId, checklistId, name, pos.Required: cardId, checklistId
checklist_item_createMutation / transfer: Add an item; due/assignee may be unconfirmed.Parameters: boardId, checklistId, name, pos, checked, due, memberId.Required: checklistId, name
checklist_item_findRead: Filter a checklist's items by nameFilter.Parameters: boardId, checklistId, nameFilter.Required: checklistId
checklist_item_updateMutation / transfer: Update a verified item; due/assignee may be unconfirmed.Parameters: boardId, checklistId, itemId, name, state, pos, due, memberId.Required: checklistId, itemId
checklist_item_deleteMutation / transfer: Delete itemId after checking membership in checklistId.Parameters: boardId, checklistId, itemId.Required: checklistId, itemId

Board members

member_findRead: Find board members by username or full name.Parameters: boardId, nameFilter.Required: none (defaults apply).

Labels

label_findRead: Find board labels by name.Parameters: boardId, nameFilter.Required: none (defaults apply).
label_createMutation / transfer: Create a board label.Parameters: boardId, name, color.Required: name
label_updateMutation / transfer: Update a label's name or color.Parameters: boardId, labelId, name, color.Required: labelId
label_deleteMutation / transfer: Delete an authorized label.Parameters: boardId, labelId.Required: labelId

Custom fields

customfield_findRead: Get field definitions, types and dropdown option ids.Parameters: boardId.Required: none (defaults apply).
customfield_setMutation / transfer: Set a typed value or dropdown option, or clear a value.Parameters: boardId, cardId, customFieldId, value, idValue.Required: cardId, customFieldId

Attachments

attachment_findRead: Find card attachment ids and metadata, with URLs for links only.Parameters: boardId, cardId.Required: cardId
attachment_addMutation / transfer: Attach an HTTP(S) URL; the server does not fetch it locally.Parameters: boardId, cardId, url, name.Required: cardId, url
attachment_uploadMutation / transfer: Upload a local path or base64 with fileName.Parameters: boardId, cardId, path, base64, fileName, mimeType, name.Required: cardId
attachment_downloadMutation / transfer: Save an uploaded attachment under the private download directory.Parameters: boardId, cardId, attachmentId.Required: cardId, attachmentId

Server diagnostics

server_healthRead: Local config health, not Trello auth. Basic/detailed credentialSource (env/file/none) means source, not validation; configured access says unverified; call workspace_find. Policy shows restrictions.Parameters: detail.Required: none (defaults apply).

Common parameters and response behavior

Selection and ownership

boardId is described per tool: collection tools default to the active board, board_use requires it, and object-scoped tools take it only as an optional expected owning-board constraint, never authorization. card_find with mine: true finds account-wide assigned cards and cannot be combined with boardId or listId. board_create requires an explicit or active workspace.

Detail and pagination

board_get, card_find and card_get support detail: "summary" (default) or "full". card_find summary returns ids, ownership, labels, members, dates, status and a description preview of at most 200 code points (omit it with includeDesc: false, which cannot be combined with full detail), with no url; full adds url, start and dateLastActivity but still previews descriptions to 200 code points. card_get keeps url and untruncated descriptions at both levels; full adds dates, checklists and members. Filters, authorization, ids and cursors match. Comments are fetched separately.

Open-card discovery in board/list/mine modes excludes archived cards. An authorized card_get can still retrieve a known archived card ID; empty discovery does not imply deletion.

view: "markdown" returns only {markdown:string}, rendering name, description, URL, due and, at full detail, checklist text. IDs, members, labels, start/activity and extras are not rendered. Request JSON for metadata or extras.

Collections return {"items":[...],"next":"cursor"}, omitting empty cursors. Cards default to 100 results (maximum 1000), comments to 20 (maximum 100), and activity/history to 20 (maximum 1000).

Argument errors identify unknown or duplicate keys and their object location. Unknown keys list allowed keys; type errors name the field and expected type.

Activity pages use the last action id as before and accept since; both take an action id or an RFC 3339 date. board_activity and card_history accept filter, default all: either all alone or comma-separated action identifiers such as commentCard, createCard or updateCard (letters, digits and underscores, starting with a letter). The grammar is open-ended and applied upstream before paging. A full page advertises a possible next page, which can be empty.

Activity, history and comments share a flat projection: id, type, date, by, then relevant fields. Omitted card/list names reuse the last supplied name for that ID in this page, else unknown. Pages start fresh. Resolve by ID with card_get/list_find if needed. These resolve current names; archived lists may remain unknown.

The card_find before cursor is a card id from the same filtered snapshot, never a date. Only 1 to 64 letters, digits, _ or - that are not a YYYY-MM-DD or YYYYMMDD date reach the fetch; others fail before any request. Missing or changed cursors never restart; snapshots are not stable across calls.

The upstream JSON response limit is 8 MiB, before local snapshot filtering/paging. limit and nameFilter run after retrieval and cannot shrink that response. A narrower listId or summary includeDesc: false may help, not guarantee recovery; omission is invalid with full detail. Smaller local pages do not fix this upstream limit, which is not an MCP output cap.

Read parameters

Every non-write tool. boardId is optional everywhere except board_use, which requires it. The repository validator checks this table against the registration and runtime schema.

Tool	Required	Optional	Defaults and accepted values
`workspace_find`	none	`nameFilter`	none
`workspace_use`	`workspaceId`	none	local selection; clears the active board
`board_find`	none	`workspaceId`, `nameFilter`	accessible open boards, including guest boards, unless `workspaceId` narrows
`board_use`	`boardId`	none	local selection
`board_get`	none	`boardId`, `detail`	`detail`: `summary` (default) or `full`
`board_activity`	none	`boardId`, `limit`, `since`, `before`, `filter`	`limit`: default 20, max 1000; `filter`: default `all`
`list_find`	none	`boardId`, `nameFilter`	open lists only
`card_find`	none	`boardId`, `listId`, `mine`, `nameFilter`, `detail`, `limit`, `before`, `includeDesc`	`detail`: `summary` (default) or `full`; `limit`: default 100, max 1000; `includeDesc`: default `true`
`card_get`	`cardId`	`boardId`, `detail`, `view`, `extraFields`	`detail`: `summary` (default) or `full`; `view`: `json` (default) or `markdown`; `extraFields`: up to four unique of `stickers`, `pluginData`, `votes` and `customFieldItems`
`card_history`	`cardId`	`boardId`, `limit`, `before`, `since`, `filter`	`limit`: default 20, max 1000; `filter`: default `all`
`attachment_find`	`cardId`	`boardId`	metadata only
`comment_find`	`cardId`	`boardId`, `limit`, `before`, `since`	`limit`: default 20, max 100
`checklist_items`	`checklistId`	`boardId`	none
`checklist_get`	`cardId`	`boardId`, `name`	`name`: default `Acceptance Criteria`
`checklist_item_find`	`checklistId`	`boardId`, `nameFilter`	case-insensitive substring
`member_find`	none	`boardId`, `nameFilter`	none
`label_find`	none	`boardId`, `nameFilter`	none
`customfield_find`	none	`boardId`	none
`server_health`	none	`detail`	`detail`: `basic` (default), `detailed`, `metadata`, `performance` or `policy`

A card_find before is a card id from the same filtered snapshot; activity, history and comment before and since take an action id or RFC 3339 date. Examples: {"cardId":"c1","view":"markdown","detail":"full"}, {"cardId":"c1","detail":"full","extraFields":["votes"]} and {"listId":"l1","includeDesc":false,"limit":50}.

Text limits

Human text is counted in Unicode code points and rejected over its limit before any request; Trello errors are never silent truncation.

Field	Local limit	Evidence
Card `desc` (`card_create`, `card_update`, batch cards)	16,384 code points	Trello's object definitions: "Up to 16384 chars"; Unicode counting undefined
Board name and `desc`, list, checklist, checklist item and label names, `checklist.items` entries	16,384 code points	Trello's API reference: up to 16384 characters at creation; Unicode counting undefined
Attachment `name`	16,384 code points	Trello's API reference: max 256 (lower than local)
Comment `text`, card names, custom-field text and `nameFilter`	16,384 code points	No documented limit; local ceiling

Requests have separate caps: 1 MiB of JSON for text-bearing tools, 14 MiB for attachment_upload and 16 KiB otherwise.

Mutations and typed values

Most writes return {id,name?,url?} or {ok:true}. Card creation can also include checklist progress and an error. Batch creation preflights arguments and referenced ids, then returns zero-based per-item results. It is not transactional: later failures do not roll back earlier cards or checklists, and batch processing continues after a per-card failure. Single-call partial results set MCP isError; batches put error and unconfirmed on entries, not the envelope, so inspect every items[] entry and read back before retrying.

Create a card with an ordered checklist

card_create and each card in card_create_batch accept checklist with an optional name (default Checklist) and required items: 1-100 nonblank strings, each at most 16,384 code points, created in order.

{"listId":"l1","name":"Sound test","checklist":{"items":["SND01","SND02"]}}

Success adds checklist: {id,name,items:N}. A checklist failure keeps the card id, the checklist id if confirmed, the confirmed item count and an error naming the failed step; do not repeat card creation, inspect with checklist_get and checklist_item_find first.

pos accepts top, bottom or 0 < pos <= 1e20 (number or JSON-number string, local bound, sent as decimal). Dates use RFC 3339. Empty due or start clears dates, and optional booleans preserve explicit false. Update tools require at least one update field.

Use customfield_find to discover field types and dropdown option ids. customfield_set requires exactly one of a typed scalar value or dropdown idValue. Clear a scalar with value: "" or a dropdown with idValue: "".

Mutation verification and partial results

Clearing due, start or a label color with an empty string is sent as query parameters, because an HTTP JSON null is ignored upstream; checklist item due and memberId do too. The response is checked first and requested values that come back are compared with no extra request. A GET happens only for fields the response omits. No retry follows an ambiguous transport failure, invalid success response or verification mismatch; HTTP 429 allows at most three.

When the object is confirmed but a requested field is not, the result is {id, error, unconfirmed}; single calls set MCP isError. The mutation may have been applied, so inspect the object before repeating anything; a created card or item is never recreated to repair a partial result. Checklist item metadata can depend on advanced checklist availability and workspace membership; a differing populated value was not applied at that observation, an unreadable one stays uncertain, and neither justifies an automatic retry.

checklist_get matches an exact name. On a miss it returns an error with the searched name, up to 20 available {id,name} choices, total and truncated, and no items.

Attachment and policy checks

attachment_upload requires exactly one confined local path or standard base64; base64 also requires fileName. Both upload and download have a 10 MiB cap. Local path uploads and attachment downloads fail closed on Windows even when directories are set. Base64 uploads and URL attachments remain alternatives subject to write/profile policy.

Basic/detailed server_health reports local presence/source, not validated auth; configured responses include access: "unverified; call workspace_find". Metadata and policy need credentials: every unconfigured detail returns only the setup response. Use workspace_find {} for an actual Trello read. Scrubbed errors distinguish auth, permission, network and rate limits; a configured 401 can mean expiry, revocation, a missing scope or no object access, so if workspace_find {} succeeds check object access or write scope. A permitted board_find can serve other profiles; health-only profiles cannot verify access. CLI status describes its invocation, not Desktop credentials; Desktop users need no CLI auth/status or credential copying.

Read the security guide for ownership and transfer rules, the setup guide to connect a client, and the source tool documentation for the full mutation table and reference-name mapping.