Content
# trello-mcp
An [MCP](https://modelcontextprotocol.io) server (stdio) that lets an AI client
like Claude Code, Claude Desktop, or Cursor read and **fully manage** a Trello
board: create boards, lists and cards, move things around, manage checklists,
labels, comments, attachments, custom fields, members, webhooks, and more.
It exposes **66 tools** covering the Trello REST API surface, so you can manage
100% of a board from your AI assistant.
## Features
- **Boards** — list, get, create, rename, archive/reopen, delete, set preferences
- **Lists** — list, get, create, rename, archive/reopen, move, move all cards
- **Cards** — list, get, create, update, move, copy, archive, delete, due dates, covers
- **Checklists** — create, list, rename, delete, add/check/update/delete items
- **Labels** — list, create, update, delete, add/remove from cards
- **Members** — list board members, assign/unassign, get profiles
- **Comments** — add, list, edit, delete
- **Attachments** — add (URL), list, delete
- **Stickers** — add to cards
- **Custom fields** — list, create, delete, set/get values (Custom Fields Power-Up)
- **Workspaces** — list, get, list boards
- **Webhooks** — list, create, delete
- **Search** — across cards and boards
## Requirements
- Node.js 18+ (for built-in `fetch`)
- A Trello account and API credentials (see below)
## Installation
```bash
git clone https://github.com/irolon/trello-mcp.git
cd trello-mcp
npm install
npm run build
```
This compiles the TypeScript sources to `build/`. The entry point is
`build/index.js`.
## Getting Trello credentials
You need two values: an **API key** and a **token**.
1. **API Key** — Log in to Trello and go to
<https://trello.com/power-ups/admin>. Create a Power-Up (any name, pick your
workspace), open it, and copy the **API Key** shown there.
2. **Token** — On that same page, click the **Token** link (or visit the
`https://trello.com/1/authorize?...` URL it shows), approve the
authorization, and copy the token string.
Full step-by-step instructions: [docs/CREDENTIALS.md](docs/CREDENTIALS.md).
> Keep both values secret. They are passed via environment variables and are
> never logged by this server. Do not commit them — `.env` is gitignored.
## Configuration
The server reads two environment variables:
| Variable | Description |
| ----------------- | --------------------- |
| `TRELLO_API_KEY` | Your Trello API key |
| `TRELLO_TOKEN` | Your Trello token |
### Claude Code (CLI)
```bash
claude mcp add trello node /absolute/path/to/trello-mcp/build/index.js \
--env TRELLO_API_KEY=your-key \
--env TRELLO_TOKEN=your-token
```
Then restart Claude Code and run `/mcp` to confirm `trello` is connected.
### Claude Desktop / Cursor / other clients
Add this to your client's MCP config (e.g. `claude_desktop_config.json`):
```json
{
"mcpServers": {
"trello": {
"command": "node",
"args": ["/absolute/path/to/trello-mcp/build/index.js"],
"env": {
"TRELLO_API_KEY": "your-key",
"TRELLO_TOKEN": "your-token"
}
}
}
}
```
On Windows, use a path like `C:/Users/you/trello-mcp/build/index.js`.
## Tools
All 66 tools, grouped by area:
| Area | Tools |
| ------------- | ----- |
| Boards | `list_boards`, `get_board`, `create_board`, `update_board`, `close_board`, `reopen_board`, `delete_board`, `set_board_pref` |
| Lists | `list_lists`, `get_list`, `create_list`, `update_list`, `archive_list`, `reopen_list`, `move_list`, `move_all_cards` |
| Cards (read) | `list_cards`, `get_card` |
| Cards (write) | `create_card`, `update_card`, `move_card`, `copy_card`, `archive_card`, `delete_card`, `set_due_complete`, `set_card_dates`, `set_card_cover` |
| Checklists | `add_checklist`, `list_checklists`, `rename_checklist`, `delete_checklist`, `add_checklist_item`, `set_checklist_item`, `update_checklist_item`, `delete_checklist_item` |
| Labels | `list_labels`, `create_label`, `update_label`, `delete_label`, `add_label_to_card`, `remove_label_from_card` |
| Members | `list_board_members`, `assign_member`, `unassign_member`, `get_me`, `get_member` |
| Comments | `add_comment`, `list_comments`, `update_comment`, `delete_comment` |
| Attachments | `add_attachment`, `list_attachments`, `delete_attachment` |
| Stickers | `add_sticker` |
| Custom fields | `list_custom_fields`, `create_custom_field`, `delete_custom_field`, `set_card_custom_field`, `get_card_custom_fields` |
| Workspaces | `list_workspaces`, `get_workspace`, `list_workspace_boards` |
| Webhooks | `list_webhooks`, `create_webhook`, `delete_webhook` |
| Search | `search` |
### Example prompts
Once connected, you can ask your assistant things like:
- "List my Trello boards."
- "Create a board called *Sprint 12* with To Do / Doing / Done lists."
- "Add a card 'Fix login bug' to the To Do list and give it a red label."
- "Move all cards from Doing to Done."
- "Add a checklist 'Release steps' to card X with three items."
## Development
```bash
npm test # run the vitest suite (no network; fetch is mocked)
npm run build # compile TypeScript to build/
```
The codebase is organized as:
- `src/config.ts` — loads and validates credentials from the environment
- `src/trello-client.ts` — typed wrapper around the Trello REST API
- `src/tools/` — one file per tool group, each defining MCP tool definitions
- `src/server.ts` — registers all tools on an `McpServer`
- `src/index.ts` — stdio entry point
Tests cover every client method and every tool's argument forwarding. `fetch`
is dependency-injected so the suite runs fully offline.
## Security
- Credentials are read only from environment variables and are **never logged**.
- The config object is never printed; only sanitized error messages surface.
- `.env`, `node_modules/`, and `build/` are gitignored.
## License
MIT
