# trello-mcp

A small [Model Context Protocol](https://modelcontextprotocol.io) server for Trello. It lets Claude Code
(or any MCP client) read the cards a customer writes for you, tick checklist items and leave comments,
without leaving the editor.

Built for a real workflow: the product owner on my current project files every round of feedback as a
Trello card with a checklist. With this server the assistant reads the card, works through the items
and ticks them off as each one lands.

## Tools

| Tool | What it does |
| --- | --- |
| `trello_list_boards` | Open boards for the token's user |
| `trello_list_lists` | Lists (columns) on a board |
| `trello_list_cards` | Open cards on a board or in one list |
| `trello_get_card` | Full card: description, checklists with item ids and states, members, labels, attachments, comments |
| `trello_search_cards` | Trello search across boards (`board:X is:open @me label:bug`) |
| `trello_set_checklist_item` | Tick / untick a checklist item |
| `trello_add_comment` | Post a comment on a card |
| `trello_move_card` | Move a card to another list |

Card arguments accept an id, a short link, or the full card URL, so you can paste a link straight from Trello.
Read tools are annotated `readOnlyHint: true`; the three write tools are not, so clients can ask before running them.

## Setup

1. Get an API key and token: https://trello.com/power-ups/admin → your Power-Up → API key → "Token".
2. Build:

```sh
npm install
npm run build
```

3. Register with Claude Code (user scope, so it works in every project):

```sh
claude mcp add trello --scope user \
  -e TRELLO_API_KEY=your_key -e TRELLO_TOKEN=your_token \
  -- node /absolute/path/to/trello-mcp/dist/index.js
```

Or by hand in `~/.claude.json`:

```json
{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["/absolute/path/to/trello-mcp/dist/index.js"],
      "env": { "TRELLO_API_KEY": "your_key", "TRELLO_TOKEN": "your_token" }
    }
  }
}
```

## Development

```sh
npm test          # vitest, no network: the Trello client takes an injected fetch
npm run typecheck
npm run dev       # runs the server over stdio with tsx
```

The code is split so the interesting parts are testable without a server:

- `src/trello.ts` — typed client over the REST API, URL/short-link parsing, error mapping
- `src/format.ts` — renders cards as compact markdown for the model (ids stay visible for follow-up calls)
- `src/tools.ts` — tool definitions with zod input schemas and handlers
- `src/index.ts` — MCP wiring over stdio

## Notes

- Everything runs as the token's user: comments and ticks show up under your name in Trello.
- `stdout` is the MCP channel; the server writes diagnostics to `stderr` only.
- Trello rate limits: 300 requests per 10 s per key, 100 per 10 s per token. Normal use is far below that.