# MCPTrello

An MCP (Model Context Protocol) server exposing a small, curated set of
Trello tools — built to let an agent read and lightly update a Trello board
without hand-pasted context, and as a learning exercise in how tool
descriptions shape agent behavior (see [DESIGN_NOTES.md](DESIGN_NOTES.md)
for the reasoning behind each one).

## Tools

| Tool | Purpose |
| --- | --- |
| `list_boards` | List accessible boards (id, name, url). |
| `get_board_state` | Full open state of a board: lists with nested open cards. |
| `get_card` | Read a single card by id, including its full description. |
| `search_cards` | Free-text search for cards, across one board or all of them. |
| `create_card` | Create a card in a list. |
| `update_card` | Update a card's name, description, due date, position, members, and/or labels. |
| `move_card` | Move a card to a different list. |
| `add_checklist_item` | Add an item to a card's checklist. |
| `add_comment` | Add a comment to a card. |
| `get_card_comments` | Read a card's comment thread, newest first. |

Out of scope for this v1: full CRUD, remote/OAuth auth, rate limiting, MCP
resources/prompts, a `cc-init` command, auto-creating checklists, editing or
deleting existing comments, and caching board/list names between calls.

## Setup

### 1. Get Trello credentials

1. Go to https://trello.com/power-ups/admin and create (or select) a
   Power-Up to get an **API key**.
2. From the same key page, generate a **token** by following the "Token"
   link — this authorizes the key to act as your Trello account.

### 2. Configure environment

```
cp .env.example .env
```

Fill in `.env`:

```
TRELLO_API_KEY=...
TRELLO_TOKEN=...
DEFAULT_BOARD_ID=...   # optional — id of the board to use when `board` is omitted
```

`DEFAULT_BOARD_ID` is optional. Without it, tools that need a board either
require you to pass one explicitly or (for `search_cards`) search across
every board you can access.

### 3. Install and build

Requires Node.js **18+**.

```
npm install
npm run build
```

### 4. Register with Claude Code

```
claude mcp add trello -- node <absolute-path-to-repo>\dist\index.js
```

## Verification

- `npm run build` — TypeScript build; run after any source change.
- `npm run verify` — launches the built server as a subprocess over stdio
  using the MCP SDK's own `Client` + `StdioClientTransport`, lists all
  tools, and calls each one (including at least one error/ambiguous case
  per tool) against your real Trello account. **Requires a fully filled-in
  `.env`** — it makes real API calls.
- MCP Inspector (`npx @modelcontextprotocol/inspector --cli node
  dist/index.js --method tools/list`) is a secondary, best-effort check.
  Every published Inspector version requires Node **≥22.7.5**; on Node 18
  it will fail to start. If you want to run it, use a separate Node 22+
  installation (e.g. via nvm) rather than upgrading this project's runtime
  requirement.