trello-mcp

Universal Model Context Protocol server for Trello. Works with any MCP-compatible client: Cursor, Claude Desktop, Gemini CLI, Codex, OpenCode, and others.

Read and update Kanban cards on allowlisted boards only. Credentials stay in environment variables; nothing is logged.

Quick start

First time (recommended)

1. Install the package
2. Configure only TRELLO_API_KEY and TRELLO_TOKEN in your MCP client
3. Start the MCP server and ask your agent to set up Trello
4. The agent lists your boards, you pick one, and the selection is saved locally

No need to hunt for board ids on first install.

Already know your board id?

Set TRELLO_ALLOWED_BOARD_IDS in the MCP env and skip onboarding.

Features

• Single self-contained native binary (Go) — no Node/Bun runtime needed at runtime
• Prebuilt per-platform binaries shipped via npm optionalDependencies (esbuild-style)
• npx -y @thadeu/trello-mcp works on any machine, any Node version (the launcher is trivial)
• stdio transport (MCP standard for local tools)
• Interactive onboarding when no boards are configured
• Board allowlist via env var or saved config file
• Tools: list boards/lists/cards, get/create/update/move cards, add comments, attachments

Requirements

• Runtime: none beyond your MCP client. The published package ships a native Go binary per platform; the npx/trello-mcp launcher is plain CommonJS and runs on any Node version (even 14) — no fnm/nvm gymnastics.
• Supported platforms: macOS and Linux on x64 and arm64.
• Development: Go 1.25+ and Bun 1.2+ (build scripts).
• Trello API key and token (Power-Up admin).
• Recommended: dedicated Trello service account, not a personal user token.

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | TRELLO_API_KEY | yes | API key from Trello Power-Up admin | | TRELLO_TOKEN | yes | User token with read,write scope | | TRELLO_ALLOWED_BOARD_IDS | no | Comma-separated board ids. Optional — see Onboarding | | TRELLO_CONFIG_PATH | no | Override config file path (default: ~/.config/trello-mcp/config.json) |

Copy .env.example when developing locally. MCP clients pass these via env in server config.

Install

Option 1 — npm / npx (recommended)

npx -y @thadeu/trello-mcp

Or install globally:

npm install -g @thadeu/trello-mcp@latest

npm automatically pulls the prebuilt binary for your platform (@thadeu/trello-mcp-<os>-<arch>) through optionalDependencies.

Option 2 — From source (Go)

git clone https://github.com/thadeu/trello-mcp.git
cd trello-mcp/cli
go build -o trello-mcp .
./trello-mcp            # runs the MCP server over stdio

Cross-compile every platform package (requires Go + Bun):

bun install
bun run build          # → npm/<platform>/bin/trello-mcp

Onboarding

When TRELLO_ALLOWED_BOARD_IDS is not set and no config file exists yet, the server starts in onboarding mode:

• Setup tools work immediately
• Card/list tools are blocked until a board is selected
• After selection, all tools unlock without restarting the MCP server

What gets saved

// ~/.config/trello-mcp/config.json
{
  "allowedBoardIds": ["56c215abc7af5016b9bceadb"],
  "updatedAt": "2026-06-23T23:00:00.000Z"
}

Config priority (on server start)

1. TRELLO_ALLOWED_BOARD_IDS env var — always wins
2. Saved config file (~/.config/trello-mcp/config.json)
3. Onboarding mode when neither is set

If the env var is set, the config file is ignored. Use the env var when you want explicit, portable MCP config. Use onboarding or the config file when you prefer zero board-id setup.

MCP flow (Cursor, Claude, etc.)

Typical first-run conversation:

You:  Set up Trello for me
Agent: calls get_setup_status        → onboarding_required: true
Agent: calls list_available_boards   → [{ id, name, url }, ...]
Agent: asks which board(s) to use
You:  AS DEV
Agent: calls select_allowed_boards     → saves config, tools unlocked
You:  List cards in QA
Agent: calls list_cards                → works

Steps:

1. Connect with only TRELLO_API_KEY and TRELLO_TOKEN
2. get_setup_status — check if onboarding is needed
3. list_available_boards — list boards from your Trello account
4. User picks one or more boards by name
5. select_allowed_boards — pass the chosen board ids
6. Done — selection persisted, other tools enabled

CLI flow (terminal)

If credentials are in ~/.cursor/mcp.json, just run:

trello-mcp onboard

Credential sources (in order): shell env → .env → ~/.config/trello-mcp/.env → ~/.cursor/mcp.json → interactive prompt.

Or export manually:

export TRELLO_API_KEY=your_key
export TRELLO_TOKEN=your_token
trello-mcp onboard

For ~/.config/trello-mcp/.env, use KEY=value or export KEY=value (both work).

Interactive prompt lists boards by number, id, or name. Re-run with --force to change the saved boards.

Board id vs URL short code

Trello URLs look like https://trello.com/b/Nh2gYTTn/as-dev.

| Value | Example | Works in config? | |-------|---------|------------------| | Board id | 56c215abc7af5016b9bceadb | yes | | URL short code | Nh2gYTTn | no |

Onboarding returns the correct board id for each board. You do not need to copy it manually unless setting TRELLO_ALLOWED_BOARD_IDS by hand.

MCP client configuration

All clients use the same pattern: spawn trello-mcp (or npx) over stdio and inject env vars.

Minimal config (onboarding)

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "@thadeu/trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your_key",
        "TRELLO_TOKEN": "your_token"
      }
    }
  }
}

Use "command": "trello-mcp" if installed globally.

Full config (skip onboarding)

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "@thadeu/trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your_key",
        "TRELLO_TOKEN": "your_token",
        "TRELLO_ALLOWED_BOARD_IDS": "56c215abc7af5016b9bceadb"
      }
    }
  }
}

Multiple boards: "board_id_1,board_id_2".

Cursor

~/.cursor/mcp.json or project .cursor/mcp.json — use either config above.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "@thadeu/trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your_key",
        "TRELLO_TOKEN": "your_token"
      }
    }
  }
}

Gemini CLI

{
  "mcpServers": {
    "trello": {
      "command": "trello-mcp",
      "env": {
        "TRELLO_API_KEY": "your_key",
        "TRELLO_TOKEN": "your_token"
      }
    }
  }
}

Consult Gemini CLI MCP docs for the exact config file path on your platform.

OpenCode / Codex

{
  "mcp": {
    "trello": {
      "type": "stdio",
      "command": ["npx", "-y", "@thadeu/trello-mcp"],
      "environment": {
        "TRELLO_API_KEY": "your_key",
        "TRELLO_TOKEN": "your_token"
      }
    }
  }
}

Adjust keys to match your client schema; the server binary and env vars stay the same.

Tools

Setup (always available)

| Tool | Description | |------|-------------| | get_setup_status | Check whether board onboarding is required | | list_available_boards | All accessible boards (used during onboarding) | | select_allowed_boards | Save user-selected boards and unlock other tools |

Kanban (requires completed setup)

| Tool | Description | |------|-------------| | list_boards | Boards filtered by allowlist | | list_lists | Lists on a board | | list_cards | Cards on a board or list | | get_card | Single card details with attachments (PR links, files) | | list_attachments | Attachments on a card (GitHub PR links, URLs, uploads) | | list_card_members | Members assigned to a card (id, username, full name) | | create_card | New card in a list | | update_card | Update name, description, due date, labels, archive | | move_card | Move card to another list | | add_comment | Add comment to a card | | archive_card | Archive (close) a card | | add_attachment | Attach a URL or local file to a card |

Security

• Treat TRELLO_TOKEN like a password; never commit it.
• Restrict boards with onboarding or TRELLO_ALLOWED_BOARD_IDS.
• Use a service account token with access only to work boards.
• No delete-card tool in v1 to reduce accidental data loss.
• Server logs errors to stderr only; stdout is reserved for MCP protocol.

Troubleshooting

no prebuilt binary for <platform>-<arch>

npm did not install the platform package. Most common cause: installing with --no-optional / --omit=optional. Reinstall without it:

npm install -g @thadeu/trello-mcp        # not --no-optional

Supported platforms are macOS and Linux on x64/arm64. The binary is native Go and does not depend on your Node version — old-Node errors like SyntaxError: Unexpected token '??=' (from the previous JS build) no longer apply.

Development

The server is written in Go (cli/). The root npm package is a thin launcher plus build scripts (run with Bun).

cd cli && go run .          # run the server over stdio
cd cli && go test ./...     # tests
cd cli && go vet ./...      # vet
bun run build               # cross-compile all platforms → npm/<platform>/
bun run build:local         # only the current platform
bun run inspector           # build + MCP Inspector

Layout:

cli/                    Go MCP server (main, client, config, tools, onboard)
bin/trello-mcp.js       launcher: resolves the platform binary and execs it
scripts/build-binaries.ts  cross-compile + emit per-platform npm packages
npm/<os>-<arch>/        build output (gitignored): binary + package.json

Release

Tag a version to cross-compile, publish, and create a GitHub release:

git tag v0.2.0
git push origin v0.2.0

Workflow .github/workflows/release.yml:

1. Cross-compiles the Go binary for every supported platform (bun run build)
2. Publishes each @thadeu/trello-mcp-<os>-<arch> package to npm
3. Publishes the root @thadeu/trello-mcp (with matching optionalDependencies)
4. Creates a GitHub release with generated notes

Bump version in package.json and the optionalDependencies versions together (the build script fails if they drift).

npm publish setup (one-time)

1. Create an npm account and ensure you own the @thadeu scope
2. Create an npm Automation token
3. Add repository secret NPM_TOKEN in GitHub → Settings → Secrets → Actions

License

MIT — Copyright (c) 2026 Thadeu Esteves. See LICENSE.