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.

Related MCP server: Advanced Trello MCP Server

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

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

Boards & lists

Cards

Checklists & comments

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:

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.