Trello Guardrails

A small MCP server that lets Claude read and organise your Trello boards by name, with archive-only writes and no guessing on ambiguous names.

Why this exists

I plan most of my personal projects in Trello, across a few dozen boards. I wanted to say "move the dialogue bug to Done" in a Claude conversation and have it happen, without looking up board, list or card IDs first.

When an agent acts on your behalf, picking the wrong card or deleting a list is worse than doing nothing. So the server is built around a few rules that keep the agent's mistakes small, visible and reversible.

Atlassian also publishes an official remote Trello MCP server. This project is a local alternative with a narrower tool set, where each tool is designed around those rules.

Features

The server exposes 14 tools.

Tool	What it does
get_boards	Lists your open boards.
get_lists	Lists the open lists on a board.
get_cards	Lists the cards in a list, with due dates and the start of each description.
get_card_details	Shows one card's description, due date, URL and comments.
search_cards	Searches cards across all boards by keyword (up to 20 results).
create_card	Creates a card in a list, with an optional description.
create_list	Creates a list on a board.
create_label	Creates a label on a board, with an optional color.
add_label	Adds an existing label to a card.
add_comment	Adds a comment to a card.
move_card	Moves a card to another list on the same board.
update_card	Changes a card's name, description or due date.
archive_card	Archives a card.
archive_list	Archives a list.

Design choices

Names instead of IDs

Every tool takes human names such as board_name="Game Jam" and card_name="dialogue bug". Trello IDs are 24-character hex strings. When a model has to copy them between calls, it can copy the wrong one and still get a valid request. Names are what the user says and what the model already has in context, so there is less to get wrong.

Matching that refuses to guess

Boards, lists, cards and labels are all resolved by one function, resolve(), which follows three steps.

1. An exact name match wins, ignoring case. Asking for Done finds "Done" even when "Not Done" also exists.
2. If there is no exact match, a partial match is used, but only when exactly one item contains the text. dialogue finds "Fix dialogue bug" if no other card mentions dialogue.
3. If two or more items match, the tool does nothing and returns the candidates, so the model can ask again with a clearer name. If nothing matches, the error lists the names that do exist.

The server never picks one of several matches on the model's behalf. A wrong guess on a write is harder to notice than an error.

Every reply says what was matched

When a partial match is used, the reply names both the real item and the text it came from. For example, Moved 'Fix dialogue bug' (matched from 'dialogue') to 'Done'. This lets the person reading the conversation see what the agent actually touched, without opening Trello.

No delete

The server has no delete tool and never sends an HTTP DELETE. The only removal actions are archive_card and archive_list, which use Trello's archive. Archived items can be restored from the board menu. A test in the suite fails if a DELETE call is ever added to the code.

Clear errors

Trello API errors are turned into short messages that include the status code and a hint, such as a revoked token (401) or a rate limit (429). The model can read the message and either fix its request or tell the user what went wrong.

Install

You need Python 3.10 or newer and uv. pip also works.

The short way

If you use Claude Code, you can ask it to do the setup for you with a prompt like this one.

Set up the Trello MCP server from https://github.com/cyber-sami/trello-guardrails-mcp for Claude Desktop and Claude Code. Read the README first. Create ~/.config/trello-mcp/config.json from the example with chmod 600, and leave the placeholders for me to fill in. Don't ask me to paste my key or token into this chat.

The last sentence matters. Your token then goes straight into a file you control and never appears in a conversation transcript. You still need the key and token from step 1 below.

The manual steps follow.

1. Get a Trello API key and token

1. Open the Trello Power-Up admin page, create a Power-Up and generate an API key for it.
2. On the same page, follow the Token link next to the key and approve access for your account.

2. Add the server to your client

You do not need to clone the repo. uvx fetches and runs it from GitHub.

Claude Code

claude mcp add --transport stdio --env TRELLO_API_KEY=your_key --env TRELLO_TOKEN=your_token trello -- uvx --from git+https://github.com/cyber-sami/trello-guardrails-mcp trello-mcp

Claude Desktop

Open Settings, then Developer, then Edit Config, and add this to claude_desktop_config.json.

{
  "mcpServers": {
    "trello": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/cyber-sami/trello-guardrails-mcp", "trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your_key",
        "TRELLO_TOKEN": "your_token"
      }
    }
  }
}

Restart Claude Desktop after saving. If it cannot find uvx, replace "uvx" with the full path that which uvx prints.

Keeping credentials out of the client config

If you do not want the token in your client config, leave out the env block and put the credentials in a file instead.

mkdir -p ~/.config/trello-mcp
cp config.example.json ~/.config/trello-mcp/config.json
chmod 600 ~/.config/trello-mcp/config.json

Then fill in the two values. The server looks for credentials in this order.

1. The TRELLO_API_KEY and TRELLO_TOKEN environment variables.
2. The JSON file named by the TRELLO_CONFIG environment variable.
3. ~/.config/trello-mcp/config.json.

Running from a clone

git clone https://github.com/cyber-sami/trello-guardrails-mcp
cd trello-guardrails-mcp
uv sync
uv run pytest
uv run trello-mcp

With pip, run pip install . inside the clone. That installs the trello-mcp command.

Example prompts

• "What's on my Game Jam board? Summarise what's in progress."
• "Create a card called 'Record footstep sounds' in To Do on Game Jam, due next Friday."
• "Move the dialogue bug to Done and add a comment saying it was fixed in the latest build."
• "Find every card that mentions the interrogation scene."
• "Create a red label called Blocker on Game Jam and put it on the lighting card."
• "Archive the Ideas list on my Home board. I'll restore it if I need it."

Security notes

Credentials are read only from environment variables or a local JSON file outside the repo. Nothing in this repository contains a real key or token, and .gitignore excludes .env and config.json files. When you use the env block, your MCP client stores the token in its own config file in plain text, so treat that file as sensitive.

The key and token are sent to api.trello.com in the Authorization header over HTTPS. They are never put in URLs, so they stay out of proxy logs and error messages.

A Trello token has the same access as your account on every board you can see. The server can read boards, lists, cards and comments. It can create cards, lists, labels and comments, move and rename cards, change descriptions and due dates, and archive cards and lists. It cannot delete anything, change board members or settings, or touch attachments and checklists. If you want a narrower blast radius, create a token that expires, or use a separate Trello account that only belongs to the boards you want Claude to manage.

Card titles, descriptions and comments are text written by people, and the model reads them as tool output. A card shared with you could contain instructions aimed at the model. Your MCP client's tool approval prompts are the defence against that, so keep write tools on "ask" if you work on boards with people you don't trust.

Limitations

• update_card replaces the name or description rather than editing it. The previous text is not kept by this server, though Trello's activity log may show it.
• An empty field means "leave unchanged", so a description or due date cannot be cleared through this server.
• move_card only moves cards within one board.
• Name lookups fetch the board's lists or cards on every call, with no caching. This is fine for personal boards and slower on very large ones.
• search_cards returns at most 20 results, and get_cards shows only the first 100 characters of each description.
• get_card_details shows the comments Trello returns by default, which is the most recent 50.
• Checklists, attachments, members, custom fields and board creation are not supported.
• The server runs over stdio only, one user per process. It is not built to be hosted for several users.
• Due dates are passed to Trello as given, without validation.

How it was built

I designed this server, decided on its tool set and guardrails, tested it against my own boards and maintain it. The code was written by Claude Code working from my specifications and reviews. The test suite runs without network access by replacing the Trello API with a fake.

License

MIT. See LICENSE.