trello-mcp

A Model Context Protocol server for Trello — connect AI agents to your boards with per-project configuration and credentials that stay on your machine.

Works with Cursor, Claude Desktop, VS Code Copilot, and any MCP-compatible client.

Quick setup for AI agents

Paste this one line into Cursor, Claude Code, Codex, Grok, or any agent that can fetch URLs:

Fetch https://raw.githubusercontent.com/asim-altayb/trello-mcp/main/docs/agent-setup/prompt.md and follow every step to install trello-mcp and wire it to this project.

The agent will detect your OS (Linux, macOS, or Windows), clone the server, configure credentials, write .trello-mcp.json, and register MCP — without you running terminal commands.

See AGENTS.md and docs/agent-setup/prompt.md for details.

Why use this?

Most Trello MCP integrations focus on hosted OAuth or a single global board. This server is built for developers who juggle multiple codebases and want:

• Local access — your API key + token, stored locally in .env
• Per-project boards — each repo declares which Trello boards belong to it
• Board aliases — reference sprint or backlog instead of raw board IDs
• Agent-ready output — JSON or Markdown responses

Comparison

Feature	trello-mcp	Atlassian Trello MCP	@delorenj/mcp-server-trello
Auth	API token (local)	Cloud OAuth	API token
Per-repo board profiles	.trello-mcp.json	One workspace	Global config
Board aliases	Yes	No	No
Markdown output	Yes	N/A	Yes
Checklists + comments	Yes	Partial	Yes
Rate limiting	Built-in	Hosted	Built-in
Best for	Multi-project workflows	Team OAuth setups	Full-featured installs

Quick start

1. Clone and configure credentials

git clone https://github.com/asim-altayb/trello-mcp.git
cd trello-mcp
npm install
npm run setup
npm run build

npm run setup saves TRELLO_API_KEY and TRELLO_TOKEN to .env.

Get credentials from Trello Power-Up Admin → API Key tab.

2. Pin boards to a project

From any project directory:

TRELLO_PROJECT_ROOT=/path/to/your/project npm run init-project

This writes .trello-mcp.json:

{
  "name": "my-app",
  "boards": [
    { "id": "abc123", "name": "Sprint Board", "alias": "sprint", "default": true },
    { "id": "def456", "name": "Backlog", "alias": "backlog" }
  ]
}

Safe to commit — board IDs only, no secrets.

3. Connect your AI client

Add to .mcp.json (Cursor / Claude Code) or your client's MCP config:

{
  "mcpServers": {
    "trello-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/trello-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Restart the client after saving.

See mcp-config.example.json for a copy-paste template.

Example prompts

• "Show my project Trello overview"
• "What's on the sprint board?"
• "Search for auth bug in this project's boards"
• "Create a card: Fix webhook retry"
• "Mark the first checklist item complete on card X"

Tools

Project context

Tool	Description
trello_project_info	Active project, configured boards, default board
trello_project_overview	All project boards → lists → cards

Boards & lists

Tool	Description
trello_list_boards	Project boards (or all with allBoards: true)
trello_get_board	Board with lists and cards
trello_list_lists	Lists on a board
trello_get_recent_activity	Recent board activity
trello_add_list	Create a list

Cards

Tool	Description
trello_get_my_cards	Cards assigned to you
trello_get_card	Full card details
trello_get_cards_in_list	Cards in a list
trello_create_card	Create a card
trello_update_card	Update card fields / labels
trello_move_card	Move card to another list
trello_archive_card	Archive a card
trello_search	Search cards/boards

Checklists & comments

Tool	Description
trello_add_checklist	Add checklist to card
trello_add_checklist_item	Add checklist item
trello_update_checklist_item	Update text or completion
trello_delete_checklist_item	Delete checklist item
trello_add_comment	Add comment
trello_get_card_comments	List comments
trello_update_comment	Edit comment
trello_delete_comment	Delete comment

Board tools accept optional board (ID, alias, or name). When omitted, the project default is used.

Multi-project setup

One shared server install; each repo gets its own .trello-mcp.json:

OS	Shared server + .env
Linux / macOS	~/.local/share/trello-mcp/
Windows	%LOCALAPPDATA%\trello-mcp\

SERVER_DIR/                → .env (credentials, once)
~/project-a/               → .trello-mcp.json (boards 1, 2)
~/project-b/               → .trello-mcp.json (boards 3, 4)

Point each project's MCP config cwd at that project. The server picks up the right boards automatically.

Security

• Never commit .env — it contains your API token
• .trello-mcp.json is safe to commit (board IDs only)
• Revoke tokens anytime: Trello → Account → Applications

Development

npm run build
npm test
npm run dev

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md.

License

MIT — see LICENSE.