The Trello MCP server gives an agent 52 tools to read and change Trello boards, lists, cards, checklists, comments, labels, attachments, members and custom fields over stdio, with trimmed replies, workspace guarding and reasoned refusals.
Browse and manage boards and workspaces: list boards/workspaces, set active board/workspace, create a board, list boards in a workspace, and fetch recent activity.
Manage lists: get, add, update, archive, watch, and reposition lists on a board.
Manage cards: add one card or a duplicate-safe batch of up to 50, get cards by list/ID/number, search cards, update details, move, copy, archive, watch, view history, and get assigned cards.
Work with comments: get, add, update, and delete comments on cards.
Work with checklists: create checklists with items, get items/by name/acceptance criteria, find items by description, add/update/delete items, and copy checklists.
Handle attachments: attach an HTTPS link, a local file from TRELLO_ATTACH_ROOT, or inline base64 data; download uploaded attachments up to 5 MB by default.
Manage labels and members: get board labels, create/update/delete labels, add/remove labels on cards, get board members, and assign/remove members on cards.
Use custom fields: read board custom field definitions and set or clear a card's custom field value.
Rely on safety and efficiency limits: trimmed replies with raw: true for full data, a workspace guard, board checks, reasoned McpError refusals, rate-limit queuing, and archiving instead of deleting cards/lists/boards.
Provides 52 tools for reading and changing Trello boards, lists, cards, checklists, comments, labels, attachments, custom fields and members. Supports card numbers, duplicate-safe batches of up to 50 cards, search, a workspace guard, rate-limited retries, and trimmed replies written for agents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Trello MCP add a card to my To Do list about the landing page redesign"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This repository is a Model Context Protocol (MCP) server for Trello. An agent uses its 52 tools to read and change boards, lists, cards, checklists, comments, labels and attachments. The server runs on the user's machine and talks to the agent over standard input and output (stdio). It calls the Trello web API with the user's key and token. Every reply is written for an agent, which reads each word of it and pays for each word in context.
Trello runs its own hosted MCP server, at https://mcp.trello.com/v1. That server cannot touch comments, and its support for checklists is limited, yet those are most of what a board is worth reading for. This server is a fork of delorenj/mcp-server-trello, taken at the tag fork-point on upstream commit 737292f of 2026-09-15. The fork drops the server's health and repair tools, fixes the broken tools, and merges the four attachment tools into one. It adds label and search tools, card numbers, duplicate-safe batches, a workspace guard, trimmed replies and limits that refuse with a reason.
The server goes as far as one Trello account and the boards that the account can reach. It can archive a card or a list, but it cannot delete a card, a list or a board. It only responds to calls, so it does not react to changes made in Trello. The agent skill in skills/trello-mcp/ tells an agent which tool to use and what to watch. An agent gets every reply trimmed to what it reads, and every refusal with its reason.
What it covers | Where |
Boards and workspaces, and the active board |
|
Lists |
|
Cards, with card numbers, search and batches of up to 50 |
|
Comments |
|
Checklists and acceptance criteria |
|
Attachments: links, local files and inline data |
|
Labels and members |
|
Custom fields |
|
Retries, the rate limit and the workspace guard |
|
Trimmed replies and the markdown card |
|
The agent skill |
|
Security policy |
|
Related MCP server: trello-mcp
npm ci # the exact versions in package-lock.json
npm run build # compiles src/ into build/
npm test # unit tests, and the smoke tests when .env.ci names a test board
npm start # the server on stdio, with the settings of section 1.1
npm run typecheck
npm run lint # ESLint and Prettier, as package.json sets them
npm run format # rewrites src/ and tests/ to the Prettier style
npm run test:unit # offline tests only
npm run test:smoke # live tests only, section 1.3The server needs Node.js 22 or later, and every other dependency is in package.json.
The server reads its settings from the environment when it starts. It reads no .env file itself, so the client that starts it must pass them. example.env lists each one with a comment. A limit with a value that is not a positive number stops the server at once, with the reason on standard error.
Setting | Need | Effect |
| required | The API key of a Trello app, from |
| required | The token of the same account, from the authorization address in |
| optional | The first active board, section 3. |
| optional | Workspace IDs, separated by commas. When set, the workspace guard of section 3 is on. |
| optional | The one folder that a |
| optional | The most characters in a card description. The default is 2400. |
| optional | The largest file that |
| optional | A proxy for every call to Trello. |
| smoke tests only | The scratch board of section 1.3. |
| smoke tests only, optional | A second board in the workspace of the scratch board, that workspace, another workspace, and a board in it. Each one turns on the move test or the workspace guard tests. |
An MCP client starts the server as a child process. Most clients take an entry of this shape, in their configuration file:
{
"mcpServers": {
"trello": {
"command": "node",
"args": ["/absolute/path/to/trello-mcp/build/index.js"],
"env": {
"TRELLO_API_KEY": "<your key>",
"TRELLO_TOKEN": "<your token>"
}
}
}
}Give the full path to build/index.js, because the client starts the server from a folder of its own. The entry holds the key and the token, so keep that file out of git, as this repository does with .mcp.json. The skill in skills/trello-mcp/ goes to the agent as one folder. Link or copy that whole folder into the agent's skills folder, for example ~/.claude/skills/trello-mcp.
The two suites answer different questions, and they live apart.
Suite | Folder | Needs | Proves |
Unit |
| only | The code does what we think Trello expects. Every call goes to a mocked Trello. |
Smoke |
|
| Trello accepts the calls. The suite starts |
The smoke suite skips itself when one of its three settings is absent, and npm test then works without a Trello account. The suite starts the built server, so npm test and npm run test:smoke build first, while npm run test:unit runs against the source. A full smoke run took 96 seconds on 2026-09-30, and its search test can wait up to 5 minutes for Trello's search index.
GitHub Actions runs both suites, and both workflows start on every push to main. The tests workflow also checks each pull request, with the typecheck, the lint, the build and the unit tests on Node.js 22 and 24. Blacksmith hosts it, except for a Dependabot pull request, which takes a GitHub-hosted runner. The smoke workflow adds a run every second Monday and a manual start, and a missing setting fails it. Its key and token are secrets of the smoke environment, which admits only main, so a fork cannot reach them. They belong to a test account that can reach only the test boards.
CodeQL and the OpenSSF Scorecard check the security of the repository, and both report to the Security tab. CodeQL analyzes the TypeScript, JavaScript and workflow files whenever the tests run, and again every Monday. The Scorecard rates the supply-chain practice of the repository after each push to main and on the same Monday schedule. Dependabot checks the npm packages and the pinned actions once a month, or at once when a security advisory appears. Each pull request that it opens is reviewed and merged by a person. Anyone who finds a vulnerability reports it in private, through the channel that .github/SECURITY.md describes.
When an agent reports that the server is down, or that a tool is absent, take these steps in order.
Run npm run build. The client starts build/index.js, and a fresh clone has no build/.
Start the server by hand with the same settings as the client: TRELLO_API_KEY=<key> TRELLO_TOKEN=<token> node build/index.js.
A healthy server stays silent and waits for input. Stop it with Ctrl+C.
When it stops at once, read the line on standard error. It names the setting that is absent or wrong.
Check that the path in the entry of section 1.2 is absolute. Then restart the client, which reads its configuration only when it starts.
When every call fails with Trello returned 401, the token is wrong or revoked. Make a new token.
To see the tools and call one by hand, run the MCP Inspector: npx @modelcontextprotocol/inspector node build/index.js.
src/ index.ts, which reads the settings and starts stdio, and server.ts, which registers the tools
src/tools/ the tools, one file for each area, with their inputs and descriptions
src/trello/ the calls to Trello: the client, retries, the guard, the batch and the checks
src/reply/ what goes back to the agent: the reply helpers, the shapers, the markdown card
tests/unit/ offline tests against a mocked Trello, one file for each source file
tests/smoke/ live tests against the Trello web API, on a scratch board
.github/workflows/ the tests, smoke, CodeQL and Scorecard workflows
.github/dependabot.yml the monthly update checks for the npm packages and the actions
.github/SECURITY.md the security policy, and the private way to report a vulnerability
skills/trello-mcp/ the agent skill: SKILL.md, and every tool in references/tools.md
docs/ the roadmap and the assurance case
docs/images/ the wide screenshot in this readme, and a square one
build/ the compiled server, which npm run build writes and git ignoresThree terms carry the rest of this document.
Concept | Meaning | Where |
Active board | The default board for any call that does not name one. It starts as |
|
Trimmed reply | A reply cut to the fields that an agent reads, under Trello's own field names. The full reply adds plugin data, badges and display settings that cost context but rarely matter to an agent. |
|
Workspace guard | A check on every request when |
|
A boardId given beside a list or a card works as a check: the server refuses a list or a card on any other board.
Each rule states what to do, and its reason states what goes wrong otherwise.
Rule | Reason |
Give every new tool a trimmed reply, through | A raw Trello reply is mostly identifiers and display data, and the agent pays for every word of it in context. |
Offer | It lets an agent inspect a full object. A write returns the object that it changed, and the trimmed form confirms the change. |
Update the skill in the same commit as the tool. | Agents rely on |
Add a call for every new tool to | That test is the only unit test that reaches a tool handler, and it fails for a tool without a call. |
Never retry a write after a server error or a lost reply. | Trello may have completed the write before the failure, so a blind retry creates a duplicate. The interceptor in |
Add every new route to the workspace guard. | The guard refuses a route that it cannot trace to a workspace. An unlisted route therefore fails whenever |
Report every refusal as an |
|
Read local files only through the attach folder check. | Card text can ask an agent to attach a key or a |
Run the smoke tests against a scratch board only. | The suite creates, edits and archives real cards, checklists, comments and labels on the board in |
Remove a retired tool completely: its registration, shaper, tests, client method and row in | A part that stays is dead code, or a row that describes a tool that no longer exists. |
Port upstream fixes by hand. | This fork splits upstream's single |
These commands show what upstream changed since the fork, and what this fork changed:
git remote add upstream https://github.com/delorenj/mcp-server-trello.git
git fetch upstream
git log fork-point..upstream/main -- src/ # upstream work since the fork
git diff fork-point..HEAD # all of our work since the forkEach tool returns one reply, and the agent reads it as text. The table gives each form of reply.
Reply | Form |
Success | Compact JavaScript Object Notation (JSON), trimmed. A few tools confirm in plain words, as |
Success with | Trello's full JSON reply. |
| The card as markdown. Markdown wins when |
| An image as MCP image content, and any other file as base64 in JSON. |
Failure |
|
Batch stop |
|
The code in a failure says which side was wrong.
Code | Meaning |
-32602 | The input is wrong, or a check refused it: a limit, a board check or the workspace guard. |
-32600 | An attachment source is wrong, or the attach rules refused it. |
-32603 | Trello or the network failed. The reason follows, as |
The 52 tools, with every input of each, are in skills/trello-mcp/references/tools.md.
Limitation | Reason |
Cards, lists and boards cannot be deleted | Trello cannot undo a deletion, while an archived card or list can be restored. |
A batch of cards is not all or nothing | The Trello API does not support transactions, so the cards created before a failure remain on the board. The stop report names them. |
One Trello account for each server | The key and the token authenticate a single account. A second account needs a second client entry. |
No live updates from Trello | The server only responds to calls over stdio, and it does not use webhooks. |
Link attachments cannot be downloaded | Trello stores the link alone, and the file stays at its source. |
Downloads are limited to 5 MB by default | A download returns as base64 in the agent's context, about a third larger than the file. |
Attachment links must use | Plain HTTP can be read or altered in transit, and a private address exposes the local network. |
The workspace guard accepts workspace IDs only | Trello identifies a board's workspace by its ID, so a workspace name in |
Custom fields must exist before a tool can set them | No tool creates a custom field, so a person adds each field in Trello first. |
At most 100 calls in 10 seconds for each token | Trello sets this limit, and the server queues calls to stay within it. |
A new card is absent from search for a few minutes | Trello adds a new card to its search index after a delay, which was 2 to 4 minutes in the smoke tests. |
Add up to 50 cards to a list, in order. Every card is checked first (the list exists, each label is on the board, each date is valid, each description is 2400 characters at most), so bad input creates nothing. A temporary Trello or network fault is retried. Any other failure stops the batch, and the reply says which cards were created and which were not: ask the user how to resolve it before retrying.
Inputs: cards (required), listId (required).
Add a new card to a specified list on a specific board
Inputs: name (required), listId (required), start, labels, +4 more.
Add a new item to a checklist
Inputs: text (required), checkListName (required), cardId, boardId.
Add the given text as a new comment to the given card
Inputs: text (required), cardId (required).
Add one label to a card. The labels already on the card stay. Get label IDs from get_board_labels.
Inputs: cardId (required), labelId (required).
Add a new list to the specified board
Inputs: name (required), boardId.
Send a card to the archive. Name the card by its ID or by its number on a board.
Inputs: cardId, boardId, cardNumber.
Send a list to the archive on a specific board
Inputs: listId (required), boardId.
Assign a member to a specific card
Inputs: cardId (required), memberId (required).
Attach something to a card. The start of source decides what happens: https:// stores a link, and the file stays at that URL; file:// uploads a local file from the folder in TRELLO_ATTACH_ROOT, and is refused when that is not set; data:;base64, uploads inline data.
Inputs: cardId (required), source (required), name, mimeType.
Copy/duplicate a Trello card to any list (even on a different board). Copies all properties by default including checklists, attachments, comments, labels, etc.
Inputs: listId (required), sourceCardId (required), pos, name, +2 more.
Copy a checklist (with all its items) from one card to another. Works across different boards.
Inputs: cardId (required), sourceChecklistId (required), pos, name.
Create a new Trello board optionally within a workspace
Inputs: name (required), desc, defaultLists, defaultLabels, +1 more.
Create a checklist on a card, with its items in the same call. Name it "Acceptance Criteria" for acceptance criteria.
Inputs: name (required), cardId (required), items.
Create a new label on a board
Inputs: name (required), color, boardId.
Delete a checklist item from a card
Inputs: cardId (required), checkItemId (required).
Delete a comment from a Trello card
Inputs: commentId (required).
Delete a label from a board
Inputs: labelId (required).
Download an uploaded attachment from a card. Returns base64-encoded data that can be saved or viewed. A link attachment has no file on Trello, and a file over 5 MB would flood the context, so both are refused.
Inputs: cardId (required), attachmentId (required).
Search for checklist items containing specific text in their description
Inputs: description (required), cardId, boardId.
Get a card's (or board's) acceptance criteria. Matches a checklist named "Acceptance Criteria", "AC", "DoD", or "Definition of Done" (case-insensitive); first match in that order wins. Returns a {found: true|false} union; read reason when not found.
Inputs: cardId, boardId.
Get information about the currently active board
Inputs: no named parameters.
Get all custom field definitions on a board. Returns field IDs, names, and types. For dropdown/list fields, also returns available options with their IDs. No tool creates a field, so a board without fields returns an empty list.
Inputs: boardId.
Get all labels of a specific board
Inputs: raw, boardId.
Get all members of a specific board
Inputs: raw, boardId.
Get detailed information about a card, by its ID or by its number on a board. The number is the one Trello shows on the card and a branch name carries, as 53 in fix/53-chat-button.
Inputs: raw, cardId, boardId, cardNumber, +1 more.
Retrieve all comments from a specific Trello card
Inputs: cardId (required), raw, limit.
Get the history/actions of a specific card
Inputs: cardId (required), raw, limit, filter.
Fetch cards from a specific Trello list on a specific board. Descriptions are previewed by default to keep responses compact; set fields without "desc" to omit descriptions, or increase descMaxLength/omitDescThresholdBytes and use get_card for full details.
Inputs: listId (required), raw, fields, boardId, +3 more.
Get a complete checklist with all its items and completion percentage
Inputs: name (required), cardId, boardId.
Get all items from a checklist by name
Inputs: name (required), cardId, boardId.
Retrieve all lists from the specified board
Inputs: raw, boardId.
Fetch all cards assigned to the current user
Inputs: raw.
Fetch recent activity on the Trello board
Inputs: raw, limit, since, before, +1 more.
List all boards the user has access to
Inputs: raw.
List all boards in a specific workspace
Inputs: workspaceId (required), raw.
List workspaces the user has access to. If TRELLO_ALLOWED_WORKSPACES is configured, only allowed workspaces are returned.
Inputs: raw.
Move a card to a different list, potentially on a different board
Inputs: cardId (required), listId (required), pos, boardId.
Remove one label from a card. The other labels on the card stay.
Inputs: cardId (required), labelId (required).
Remove a member from a specific card
Inputs: cardId (required), memberId (required).
Search card names and descriptions by text, on one board or on every board the user can reach. Returns the name, number, board, list and link of each match.
Inputs: query (required), limit, boardId.
Set the active board for future operations
Inputs: boardId (required).
Set the active workspace for future operations
Inputs: workspaceId (required).
Set or clear a custom field value on a card. Use get_board_custom_fields first to find field IDs and types. Value format depends on type: text=any string, number=numeric string, checkbox="true"/"false", date=ISO 8601 string, list=option ID from get_board_custom_fields. To clear a field, set type to "clear" and omit value.
Inputs: type (required), cardId (required), customFieldId (required), value.
Update an existing card's details. Name the card by its ID or by its number on a board.
Inputs: pos, name, start, cardId, +7 more.
Update a checklist item name, state, position, due date, reminder, or assigned member
Inputs: cardId (required), checkItemId (required), due, pos, +4 more.
Update the given comment with the new text
Inputs: text (required), commentId (required).
Update an existing label
Inputs: labelId (required), name, color.
Update a list name, archive state, subscription state, or board. Use update_list_position for moving a list within a board.
Inputs: listId (required), name, closed, idBoard, +1 more.
Update the position of a list on the board. Trello uses fractional indexing: each list has a float position, and to place a list between two others, use the average of their positions (e.g., between pos 1024 and 2048, use 1536). Use "top"/"bottom" shortcuts to move to the edges.
Inputs: listId (required), position (required).
Subscribe or unsubscribe from watching a card for activity notifications
Inputs: cardId (required), subscribed (required).
Subscribe or unsubscribe from watching a list for activity notifications
Inputs: listId (required), subscribed (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 52 tools
Most tools target distinct resources and actions, but the checklist retrieval tools (get_checklist_items, get_checklist_by_name, get_acceptance_criteria, find_checklist_items_by_description) overlap substantially, making it unclear which to use for a basic checklist lookup. Descriptions help somewhat but do not fully resolve the ambiguity.
All tool names use snake_case with a consistent verb_noun pattern (e.g., list_boards, create_board, update_card_details, delete_comment). Minor variants like get_cards_by_list_id still fit the convention.
52 tools is far above the recommended 3-15 range and excessive for a single MCP server. While Trello's domain is broad, many operations could be consolidated or made more generic to reduce cognitive load.
The surface covers most card/list/board operations, comments, checklists, labels, members, custom fields, and attachments, but notable gaps exist: no update/delete for boards, no workspace creation/update/delete, no delete for checklists, and no custom field definition creation. These missing lifecycle operations will cause agent failures for common admin tasks.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Manage Kanera workspaces, boards, cards, checklists, comments, notes, automations, and reports.
Task boards for teams and their AI agents: cards, checklists, sprints, plans and proposals.