Trello Mcp

Trello MCP Server

A Model Context Protocol (MCP) server that connects Trello to Claude Code. Manage your boards, lists, cards, checklists, and more — all through natural language.

> 73 tools | Zero config startup | Auto-loads .env | Docker ready | Remote HTTP support

---

Prerequisites

• Node.js 22+
• Claude Code CLI installed and authenticated
• A Trello account
• Docker (only needed for remote/Docker mode)

---

Option A: Local Setup (Stdio Mode)

Best for personal use on your own machine. Claude Code launches the server automatically — no Docker needed.

Step 1: Clone and install

git clone https://github.com/GabrielRamirez/trello-mcp.git
cd trello-mcp
npm install

Step 2: Get your Trello credentials

Run the interactive setup wizard:

npm run setup

It will:

1. Ask for your API key — get one at trello.com/power-ups/admin
2. Open your browser to authorize the app
3. You click Allow, copy the token, and paste it back
4. Save both values to a .env file automatically

> The .env file is git-ignored. Your credentials stay local.

Step 3: Register the server with Claude Code

claude mcp add trello -- npx tsx src/index.ts

Step 4: Verify it works

Open Claude Code and ask:

List my Trello boards

You should see your boards listed. The 73 Trello tools are now available in every Claude Code conversation.

---

Option B: Docker Setup (Remote HTTP Mode)

Best for running on a server, sharing with a team, or keeping the server always-on. The server exposes an HTTP endpoint that Claude Code connects to via URL.

Step 1: Clone the repo

git clone https://github.com/GabrielRamirez/trello-mcp.git
cd trello-mcp

Step 2: Configure credentials

cp .env.example .env

Open .env in your editor and fill in your values:

TRELLO_API_KEY=your-api-key-here
TRELLO_TOKEN=your-token-here

Need credentials? Get your API key at trello.com/power-ups/admin, then click the token link on that page to authorize.

Step 3: Build and start the server

docker compose up --build

You should see:

trello-mcp-1  | Trello MCP server listening on http://0.0.0.0:3333/mcp

> The server will refuse to start if credentials are missing, with a clear error telling you what's needed.

Step 4: Verify the server is running

In a new terminal:

curl http://localhost:3333/health

Expected response:

{"status":"ok"}

Step 5: Connect Claude Code to the server

claude mcp add --transport http trello http://localhost:3333/mcp

If the server is running on a remote machine, replace localhost with the server's hostname or IP:

claude mcp add --transport http trello http://your-server:3333/mcp

Step 6: Verify it works

Open Claude Code and ask:

List my Trello boards

---

Option C: Using the Published Docker Image

The image is published on Docker Hub. No cloning or Node.js required.

Step 1: Run the container

docker run -d -p 3333:3333 \
  -e TRELLO_API_KEY=your_key \
  -e TRELLO_TOKEN=your_token \
  --name trello-mcp \
  gabermz/trello-mcp

Step 2: Connect Claude Code

claude mcp add --transport http trello http://localhost:3333/mcp

That's it — no Node.js, no cloning, no npm install.

---

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TRELLO_API_KEY | Yes | — | Your Trello API key (get one here) | | TRELLO_TOKEN | Yes | — | Your Trello authorization token | | PORT | No | 3333 | HTTP server port (Docker/remote mode only) |

---

Sharing with Your Team

Option 1: Project-scoped config

Register the server for everyone working in a specific project:

claude mcp add --transport http trello --scope project http://localhost:3333/mcp

This saves the config to .mcp.json in the project root, which you can commit to git.

Option 2: Manual .mcp.json with environment variable support

Create .mcp.json in your project root:

{
  "mcpServers": {
    "trello": {
      "type": "http",
      "url": "${TRELLO_MCP_URL:-http://localhost:3333}/mcp"
    }
  }
}

Each teammate can set TRELLO_MCP_URL to point to their own server, or omit it to use the default localhost:3333.

---

What Can It Do?

Once connected, just ask Claude in natural language:

| You say | What happens | |---------|--------------| | "List my Trello boards" | Fetches all your boards | | "Show me the cards in my Sprint board" | Gets all cards on that board | | "Create a card called Fix login bug in the To Do list" | Creates a new card | | "Move that card to In Progress" | Moves a card between lists | | "Add a checklist called QA Steps to that card" | Creates a checklist | | "Search for cards about authentication" | Searches across all boards | | "Add a comment: Blocked by API rate limit" | Comments on a card | | "Archive all done cards" | Archives completed cards |

---

Tools Reference

Boards (14 tools)

| Tool | Description | |------|-------------| | list_boards | List all boards for the authenticated user | | get_board | Get board details by ID | | get_board_lists | Get all lists on a board | | get_board_cards | Get all cards on a board | | get_board_labels | Get all labels on a board | | get_board_members | Get all members of a board | | get_board_actions | Get the activity feed for a board | | get_board_custom_fields | Get custom field definitions on a board | | create_board | Create a new board | | update_board | Update name, description, closed status, or background | | delete_board | Permanently delete a board (irreversible) | | create_label | Create a new label on a board | | add_board_member | Add a member to a board with a role | | remove_board_member | Remove a member from a board |

Cards (20 tools)

| Tool | Description | |------|-------------| | get_card | Get card details with checklists, labels, and members | | create_card | Create a new card on a list | | update_card | Update card name, description, due date, or position | | move_card | Move a card to a different list or board | | archive_card | Archive a card (reversible) | | unarchive_card | Unarchive (reopen) a closed card | | delete_card | Permanently delete a card (irreversible) | | add_comment | Add a comment to a card | | update_comment | Edit a comment on a card | | delete_comment | Delete a comment from a card | | add_label_to_card | Add a label to a card | | remove_label_from_card | Remove a label from a card | | add_member_to_card | Assign a member to a card | | remove_member_from_card | Unassign a member from a card | | get_card_actions | Get the activity feed for a card | | list_attachments | List all attachments on a card | | add_attachment | Add a URL attachment to a card | | delete_attachment | Delete an attachment from a card | | get_card_custom_fields | Get custom field values for a card | | update_custom_field_item | Set a custom field value on a card |

Lists (8 tools)

| Tool | Description | |------|-------------| | get_list | Get a list and all its cards | | create_list | Create a new list on a board | | update_list | Rename or reposition a list | | archive_list | Archive a list | | unarchive_list | Unarchive (reopen) a closed list | | move_all_cards | Move all cards from one list to another | | archive_all_cards | Archive all cards in a list | | move_list_to_board | Move a list to a different board |

Checklists (7 tools)

| Tool | Description | |------|-------------| | create_checklist | Create a checklist on a card | | get_checklist | Get a checklist by ID with all its items | | update_checklist | Rename or reposition a checklist | | delete_checklist | Permanently delete a checklist | | add_checklist_item | Add an item to a checklist | | update_checklist_item | Toggle, rename, or reposition a checklist item | | delete_checklist_item | Delete an item from a checklist |

Labels (3 tools)

| Tool | Description | |------|-------------| | get_label | Get a label by ID | | update_label | Update a label's name or color | | delete_label | Permanently delete a label |

Members (7 tools)

| Tool | Description | |------|-------------| | get_member | Get member info by ID or username | | get_member_cards | Get all cards assigned to a member | | get_member_boards | Get all boards a member belongs to | | get_member_organizations | Get all workspaces a member belongs to | | get_notifications | Get notifications for the authenticated user | | mark_all_notifications_read | Mark all notifications as read | | search_members | Search for members by name, username, or email |

Custom Fields (4 tools)

| Tool | Description | |------|-------------| | create_custom_field | Create a custom field definition on a board | | get_custom_field | Get a custom field definition by ID | | delete_custom_field | Delete a custom field definition | | get_custom_field_options | Get dropdown options for a list-type custom field |

Organizations (5 tools)

| Tool | Description | |------|-------------| | get_organization | Get workspace details by ID or name | | get_organization_members | Get all members of a workspace | | get_organization_boards | Get all boards in a workspace | | create_organization | Create a new workspace | | update_organization | Update workspace name, description, or website |

Webhooks (4 tools)

| Tool | Description | |------|-------------| | create_webhook | Create a webhook for model change notifications | | get_webhook | Get webhook details by ID | | update_webhook | Update a webhook's URL, model, or active status | | delete_webhook | Delete a webhook |

Search (1 tool)

| Tool | Description | |------|-------------| | search | Search boards and cards with Trello search operators (@member, #label, list:name, is:open, etc.) |

> Tools that require Trello Premium or Enterprise (Custom Fields, some board features) will return a clear error message if your account doesn't have access.

---

Project Structure

trello-mcp/
├── src/
│   ├── index.ts              # Stdio entry point (local mode)
│   ├── remote.ts             # HTTP entry point (Docker/remote mode)
│   ├── server.ts             # Shared server factory
│   ├── trello-client.ts      # HTTP client with auth and error handling
│   ├── types.ts              # TypeScript interfaces for Trello objects
│   ├── tools/
│   │   ├── boards.ts         # Board tools (14)
│   │   ├── cards.ts          # Card tools (20)
│   │   ├── lists.ts          # List tools (8)
│   │   ├── checklists.ts     # Checklist tools (7)
│   │   ├── labels.ts         # Label tools (3)
│   │   ├── members.ts        # Member tools (7)
│   │   ├── customfields.ts   # Custom Field tools (4)
│   │   ├── organizations.ts  # Organization tools (5)
│   │   ├── webhooks.ts       # Webhook tools (4)
│   │   └── search.ts         # Search tool (1)
│   └── utils/
│       ├── env.ts            # .env file loader
│       └── response.ts       # Response formatting helpers
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── package.json
├── tsconfig.json
└── tsup.config.ts

---

Troubleshooting

| Problem | Solution | |---------|----------| | "Missing required environment variables" | Copy .env.example to .env and fill in your credentials, or pass them via -e flags. | | "Trello API credentials are not configured" | Run npm run setup to configure credentials interactively. | | 401 Unauthorized | Your API key or token is invalid. Run npm run setup to generate new ones. | | Server starts but no tools appear | Make sure you used claude mcp add, not just npx tsx src/index.ts directly. | | "Cannot find module" errors | Run npm install to install dependencies. | | Docker health check failing | Ensure port 3333 isn't already in use. Check logs with docker compose logs. | | Can't connect to remote server | Check firewall rules allow port 3333. Verify with curl http://your-server:3333/health. |

---

Development

# Install dependencies
npm install

# Run in dev mode (stdio, auto-loads .env)
npm run dev

# Build for production
npm run build

# Run HTTP server locally without Docker
npm run start:remote

# Run production build (stdio)
npm run start

---

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: GabrielRamirez
• Source: GabrielRamirez/trello-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.