Content
llo-mcp
==========
[Overview]
Local stdio-based Trello MCP server. Trello API calls are made directly from the user's PC.
[Public Distribution]
- Do not include credentials, board IDs, or other identifying information in the repository (token.txt is in .gitignore).
[Requirements]
- Node.js 20+ (Mac / Windows)
- Trello API key / token
[Environment Variables]
- TRELLO_API_KEY (required)
- TRELLO_TOKEN (required)
- TRELLO_ALLOWED_BOARD_IDS (optional, comma-separated allowlist)
- TRELLO_READ_ONLY (optional, set to true to disable write tools)
[MCP Integration]
--- Cursor ---
- Configuration file: ~/.cursor/mcp.json (Mac) / %USERPROFILE%\.cursor\mcp.json (Windows)
- Example: examples/cursor.mcp.json
- Copy the mcpServers block from examples/cursor.mcp.json (set your Trello key/token)
--- Claude Code ---
- Configuration file (choose one):
- Project: {repo}/.mcp.json (team-shared, approved once with /mcp)
- User-global: ~/.claude.json's mcpServers
- Example: examples/claude-code.mcp.json
- Supports env expansion in ${_API_KEY} format → use with export in your shell
- CLI: claude mcp add local-trello --scope user -- npx -y github:telnturtle/trello-mcp
--- CodexAI) ---
- Configuration file: ~/.codex/config.toml (global)codex/config.toml (project, trusted)
- Example: examples/codex.config.toml
- CLI: codex mcp add local-trello -- npx -y github:telnturtle/trello-mcp
- Verify connection with /mcp in your session
[Common npx Example]
"command": "npx",
"args": ["-y", "github:telnturtle/trello-mcp"],
"env": {
"TRELLO_API_KEY": "your_api_key",
"TRELLO_TOKEN": "your_token"
}
[Windows Notes]
- npx method allows for consistent setup on Mac/Windows
- Install Node from nodejs.org LTS (20+)
[Installation — Running from Local Path]
- git clone https://github.com/telnturtle/trello-mcp
- cd trello-mcp && npm install && npm run build
- Reference: .env.example (do not commit actual keys/tokens)
- npm install automatically runs the prepare script (builds)
- MCP setup: see examples/cursor.local-path.mcp.json
[Board ID Guidance]
- Use API board ID (not URL short ID, verify with trello_list_boards)
[Provided Tools]
- System: trello_health
- Workspace: trello_list_workspaces, trello_list_workspace_boards
- Board/List/Card lookup: trello_list_boards, trello_list_lists,
trello_list_board_members, trello_list_cards_by_list, trello_search_cards,
trello_get_card
- Label lookup: trello_list_board_labels
- Comment trello_list_card_comments
- Writing: trello_create_card, trello_attach_url_to_card, trello_add_comment,
trello_update_comment, trello_delete_comment, trello_assign_member,
trello_remove_member, trello_move_card, trello_update_card,
trello_create_label, trello_update_label, trello_delete_label,
trello_set_card_labels, trello_archive_card
(requires confirm: true, disabled if READ_ONLY=true)
[Security]
- Inject keys/tokens only through environment variables, not in code or repository
- Board access can be restricted with an allowlist
- Descriptions and comments are excluded by default or only included with options
- Authentication info, card content, and comment text are not logged
[Local Test Scripts: TRELLO_API_KEY, TRELLO_TOKEN required
- Optional: TRELLO_TEST_BOARD_ID (for board-specific testing)
- scripts/test-readonly.mjs (read-only)
- scripts/test-mcp-readonly.mjs (MCP stdio read-only)
- scripts/test-write-workflow.mjs (write workflow, specify list/member IDs with environment variables)
[Scripts]
- npm run build — Compile TypeScript to dist/
- npm run prepare — Automatically run during npm install (build)
- npm run dev — Run with tsx for development
- npm start dist/index.js
[examples/]
- cursor.mcp.json — Cursor npx integration
- cursor.local-path.mcp.json — Cursor local node path
- claude-code.mcp.json — Claude Code .mcp- codex.config.toml — Codex config.toml
