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