# trello-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server for Trello. It gives an AI assistant read and write access to your Trello boards: list boards and cards, read a card with its comments and checklists, search, create and update cards, move them between lists, comment, label, and archive.

It runs over stdio with your own free Trello API key and token, so it works with Claude Code, Claude Desktop, Codex CLI, Cursor, and any other MCP client.

There is no delete tool. See [Safety](#safety).

## Requirements

- Node.js 20 or newer
- A Trello account (free is fine)

## Get your credentials

Trello needs two values: an **API key** and a **token**. Both are personal secrets.

1. Go to <https://trello.com/power-ups/admin> and create a Power-Up. Name and workspace do not matter; this is just how Trello hands out API keys these days.
2. Open the Power-Up's **API key** tab. The value in the "API key" field is your `TRELLO_API_KEY`.
3. In the paragraph to the right of that field ("… you can manually generate a **Token**"), click the **Token** link. Approve the access request. The long string Trello then shows you is your `TRELLO_TOKEN`.

Ignore the **Secret** field and **Allowed origins** on that page — they belong to Trello's OAuth flow, which this server does not use. The token, not the secret, is what pairs with your API key here.

The token inherits your own Trello permissions: the server can see and change exactly what you can, and nothing more. You can revoke it any time from <https://trello.com/my/account> under "Applications".

## Quick start

```bash
TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token npx -y github:rilolabs/trello-mcp
```

It will print `trello-mcp <version> ready on stdio` to stderr and then wait for MCP traffic on stdin. That is the correct behaviour — it is meant to be launched by an MCP client, not used by hand. Started without credentials, it exits immediately with instructions.

The `github:` form fetches this repository and builds it on your machine; the first run takes a minute, later runs use npx's cache. It is not published to the npm registry.

## Configuration

### Claude Code

```bash
claude mcp add trello \
  -e TRELLO_API_KEY=your-key \
  -e TRELLO_TOKEN=your-token \
  -- npx -y github:rilolabs/trello-mcp
```

### Claude Desktop

Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`) and add:

```json
{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "github:rilolabs/trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}
```

Restart Claude Desktop afterwards.

### Codex CLI

In `~/.codex/config.toml`:

```toml
[mcp_servers.trello]
command = "npx"
args = ["-y", "github:rilolabs/trello-mcp"]
env = { TRELLO_API_KEY = "your-key", TRELLO_TOKEN = "your-token" }
```

### Any other stdio MCP client

Cursor (`.cursor/mcp.json`), Windsurf, Zed, and most other clients take the same generic shape:

```json
{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "github:rilolabs/trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}
```

Transport is stdio; there is no HTTP mode.

## Tools

Ids flow downward: `list_boards` gives you board ids, `get_lists` gives list ids, `get_cards` and `search_cards` give card ids, `get_labels` gives label ids.

| Tool | Type | Parameters | What it does |
| --- | --- | --- | --- |
| `list_boards` | read | — | Every board the token can see: id, name, url, closed. |
| `get_lists` | read | `board_id` | Open lists on a board, in board order. |
| `get_cards` | read | `board_id`, `list_id?`, `label?`, `include_archived?` (false), `limit?` (50) | Cards on a board, optionally filtered to one list or one label name. Returns trimmed summaries. |
| `get_card` | read | `card_id` | One card in full: description, labels, due, members, checklist done/total, recent comments. |
| `search_cards` | read | `query`, `board_id?` | Trello search, including operators like `due:week` or `label:urgent`. Up to 25 results. |
| `get_labels` | read | `board_id` | Board labels with id, name and colour. |
| `get_board_activity` | read | `board_id`, `days?` (7) | Recent actions on a board, one readable line each. |
| `create_card` | write | `list_id`, `name`, `desc?`, `due?`, `label_ids?` | Creates a card at the bottom of a list. |
| `update_card` | write | `card_id`, `name?`, `desc?`, `due?` | Updates title, description, or due date. `due: null` clears the due date. |
| `move_card` | write | `card_id`, `list_id`, `position?` (`top`/`bottom`) | Moves a card to another list. |
| `add_comment` | write | `card_id`, `text` | Posts a comment as the authenticated user. |
| `add_label` | write | `card_id`, `label_id` | Attaches an existing board label to a card. |
| `remove_label` | write | `card_id`, `label_id` | Detaches a label from a card. The label stays on the board. |
| `archive_card` | write | `card_id` | Archives a card. Reversible. |
| `unarchive_card` | write | `card_id` | Restores an archived card to its list. |

Results come back as compact JSON with the useful fields selected, not as raw Trello API objects.

## Safety

**No delete tool, by design.** Trello's `DELETE /cards/{id}` is permanent. There is no trash and no undo, and the card's comments, checklists, and history are destroyed with it. An assistant that can delete cards can wipe out work irrecoverably on a single wrong id. `archive_card` is the reversible equivalent and covers every legitimate "get this off the board" case, so this server ships no card deletion and will not be adding one.

**Credentials stay in environment variables.** `TRELLO_API_KEY` and `TRELLO_TOKEN` are read from the environment at startup and never written to disk, never echoed to stdout, and never included in a tool result.

Trello authenticates by putting the key and token in the URL query string, which makes any raw URL in an error message a credential leak. Every error path in this server is routed through a redactor that strips `key=` and `token=` values and scrubs the secret strings themselves before anything is thrown, logged, or returned. Diagnostics go to stderr; stdout carries protocol traffic only.

**Scope.** The token has your Trello permissions, no more. If you want to limit exposure, use a Trello account that is only a member of the boards you want reachable, and revoke the token from <https://trello.com/my/account> when you are done.

## Development

```bash
npm install
npm run build     # compile to dist/
npm run dev       # run from source with tsx
```

Smoke-test the wire protocol without touching Trello:

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | TRELLO_API_KEY=x TRELLO_TOKEN=x node dist/index.js
```

Layout:

```
src/index.ts        entry point: env check, server wiring, stdio transport
src/trello.ts       Trello REST client + credential redaction
src/format.ts       result formatting and error mapping
src/tools/read.ts   read-only tools
src/tools/write.ts  write tools
```

## License

MIT © Rilo Labs