# trello-mcp

A small [MCP](https://modelcontextprotocol.io) server for Trello, built around the one
thing the popular Trello MCP servers don't do: **searching cards by custom field**
(e.g. find every card where the `AI Ready` field equals `Claude kiosk`).

It talks to the Trello REST API directly using your API key + token, returns **compact**
results (no multi-hundred-KB board dumps), and resolves boards/cards by id, 8-char
shortLink, URL, or name.

## Tools

| Tool | What it does |
|------|--------------|
| `list_boards` | All boards you can access — `{id, name, shortLink, url}`, nothing else. |
| `list_custom_fields` | Custom fields on a board + the allowed options for `list`-type fields. Use it to discover field names/values. |
| `find_cards` | **Main tool.** Find cards on a board, filtered by a custom field (`fieldName` + `value`, or `values` to match ANY of several), and/or `listName`, and/or `label`. Matching is case-insensitive (exact first, then substring). Omit value(s) to match "field is set". |
| `get_card` | Full content of one card: description, custom field values, checklists, attachments, comments, members, due date. |
| `add_comment` | Post a comment to a card (ask a clarifying question, or log progress). |
| `set_custom_field` | Set/clear a custom field on a card; `createOption:true` adds a new list option. Used to mark status (e.g. `AI Ready → Done`). |
| `attach_file` | Attach a file to a card — a local file by `path` or a remote file by `url`. Handy for posting a result file when finishing a task. |

## Setup

### 1. Get Trello credentials
Create a Power-Up at <https://trello.com/power-ups/admin>, grab the **API Key** from its
*API Key* tab, then generate a **Token**:

```
https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&name=trello-mcp&key=YOUR_API_KEY
```

> The Power-Up **Secret** is for OAuth and is NOT used here — only `API Key` + `Token`.

### 2. Register with Claude Code — zero clone, straight from GitHub
```bash
claude mcp add trello-cf --scope user \
  -e TRELLO_API_KEY=YOUR_KEY \
  -e TRELLO_TOKEN=YOUR_TOKEN \
  -- npx -y github:AxGrid/trello-mcp
```
`--scope user` makes it available in every project. `npx` installs and runs it on
first launch — no `git clone`, no `npm install`. Restart Claude Code afterwards.

Or in `claude_desktop_config.json` / any MCP client:
```json
{
  "mcpServers": {
    "trello-cf": {
      "command": "npx",
      "args": ["-y", "github:AxGrid/trello-mcp"],
      "env": { "TRELLO_API_KEY": "YOUR_KEY", "TRELLO_TOKEN": "YOUR_TOKEN" }
    }
  }
}
```

> `npx` caches the GitHub package per resolved commit. To force a pull of the latest
> `main`, clear it once: `npx clear-npx-cache` (or `rm -rf ~/.npm/_npx`).

### Local / dev install
```bash
git clone git@github.com:AxGrid/trello-mcp.git && cd trello-mcp && npm install
# then point the client at: node /abs/path/to/trello-mcp/server.mjs
```

## Example

> Find cards on the *Stellar Kiosk* board where **AI Ready = Claude kiosk** and let's solve them.

Claude calls `find_cards({ board: "Stellar Kiosk", fieldName: "AI Ready", value: "Claude kiosk" })`,
then `get_card(...)` on the match.

## Task lifecycle via a custom field

A single list-type field (here `AI Ready`) doubles as a status. Suggested values:

| State | Value | How |
|-------|-------|-----|
| Queued for AI | `Claude kiosk`, `Claude Module`, … | pick up with `find_cards({fieldName:"AI Ready", values:["Claude kiosk","Claude Module"]})` |
| Needs a human answer | `Need response` | `set_custom_field(card, "AI Ready", "Need response", createOption:true)` + `add_comment(card, "question…")` |
| Done | `Done` | optionally `attach_file(card, path:"…/result.…")`, then `set_custom_field(card, "AI Ready", "Done", createOption:true)` |

Setting a new state moves the card out of the "queued" search automatically, since the
field no longer equals a queued value. `createOption:true` is only needed the first time
a value is introduced.

## Self-test
Runs the core logic against your real account (read-only):
```bash
TRELLO_API_KEY=... TRELLO_TOKEN=... TEST_BOARD="Your Board" node selftest.mjs
```

## Requirements
Node 18+ (uses the built-in global `fetch`). The only runtime dependency is
`@modelcontextprotocol/sdk`.