trello-mcp

trello-mcp

A self-hostable Model Context Protocol server that lets MCP-compatible clients work with Trello cards, lists, labels, attachments, checklists, members, and card activity.

The project is intentionally self-hostable and reusable. Contributions, adaptations, and focused issue reports are welcome.

The roadmap is, of course, tracked on Trello, and trello-mcp helps keep it up to date: trello-mcp roadmap.

Disclaimer

trello-mcp is an independent, community-maintained project. It is not an official Trello or Atlassian product, service, or MCP implementation, and it is not affiliated with, endorsed by, or sponsored by Trello or Atlassian.

This project exists to make it easier for MCP-compatible LLM clients to interface with Trello through Trello's public API and user-provided API credentials.

Looking for Trello's official hosted MCP server? Visit Trello MCP and use the endpoint documented by Trello: https://mcp.trello.com/v1.

Documentation

The complete project documentation is available at trello-mcp.com:

• Get started
• Create a Trello API key and token
• Set up your MCP client
• Browse the tool catalog
• Review API coverage and non-goals
• Understand Security & Data
• Operate a running deployment
• Troubleshoot an installation
• Official MCP Registry installation, releases, and recovery
• Glama listing (validation status)

Features

Board Discovery

• List boards visible to the authenticated Trello member.
• Read basic board metadata.
• List open, closed, or all lists on a board.
• List open, closed, visible, or all cards on a board.
• List board labels, members, and memberships.
• Create, inspect, update, and delete board labels.
• Create, inspect, rename, archive, unarchive, and move lists between boards.

Card Workflows

• Read cards by id, short id, or Trello card URL.
• Create cards with title, description, due date, position, members, and labels.
• Update card metadata including title, description, due date, due completion, and archived state.
• Move cards between lists or boards.
• Apply and remove existing labels on cards.
• Permanently delete cards only when explicitly requested.

Card Context

• List cards in a Trello list.
• List card attachments, inspect individual attachments, add public URL attachments, and upload server-local files from an explicitly configured directory.
• List, create, rename, and delete card checklists, and manage checklist items.
• List card members and add or remove members.
• Read card actions and activity history.
• Add, edit, and delete Trello card comments.

Search Workflows

• Search Trello cards, boards, members, and workspaces using Trello search text and operators.
• Scope search results to specific boards, cards, or workspaces.
• Look up Trello members by name or username before assignment.
• Read member profiles, assigned cards, boards, and workspaces.

Workspace Discovery

• List Trello workspaces visible to the authenticated member.
• Read workspace metadata, boards, and members.

Self-Hosted Runtime

• Run with Docker Compose using the published GHCR image.
• Build locally with a separate Compose file.
• Use Streamable HTTP for container deployments.
• Use stdio for local MCP clients that launch the server as a child process.
• Keep stdio logs on stderr so local MCP clients receive protocol-only stdout.
• Expose HTTP health and readiness endpoints.
• Optionally require a bearer token for HTTP MCP endpoint requests.
• Validate config, tool input, and Trello API responses with Zod.
• Redact Trello credentials from logs.
• Run typecheck, lint, build, tests, and coverage in GitHub Actions.

Quick Start

1. Get Trello API Credentials

Trello API keys are created from an app in Trello's App Admin Portal. Each person running this server should use their own Trello account and token. Follow the dedicated Trello API credentials guide for the current, security-focused walkthrough.

In short: create or select an app at trello.com/apps/admin, generate a key from its API Key tab, then use the nearby Token link to review and authorize access for the intended Trello member.

You will use those values as:

TRELLO_API_KEY=your-api-key

TRELLO_TOKEN=your-token

2. Choose an Install Path

Option A: Run the Published Docker Image

Use this path if you just want to run the server. It pulls the prebuilt image from GHCR and does not build anything locally.

git clone https://github.com/enthouan/trello-mcp.git

cd trello-mcp cp .env.example .env

Edit .env and replace the placeholder values:

TRELLO_API_KEY=your-api-key

TRELLO_TOKEN=your-token TRANSPORT=http LOG_LEVEL=info TRELLO_RATE_LIMIT_CAPACITY=100 TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS=10000 TRELLO_RETRY_MAX_ATTEMPTS=3 TRELLO_RETRY_BASE_DELAY_MS=100 TRELLO_RETRY_MAX_DELAY_MS=2000

MCP_AUTH_TOKEN=optional-shared-secret

TRELLO_MCP_HOST_BIND_IP=127.0.0.1 TRELLO_MCP_HOST_PORT=3000 TRELLO_MCP_IMAGE_TAG=latest TRELLO_MCP_NETWORK=trello-mcp_network

Start the published image:

docker compose up -d --wait --wait-timeout 120

The default docker-compose.yml uses:

ghcr.io/enthouan/trello-mcp:latest

Docker Compose values such as image tag, host bind IP, host port, and network name can be overridden with environment variables or the .env file. The compose files document their defaults at the top; for example, TRELLO_MCP_IMAGE_TAG defaults to the latest tag in docker-compose.yml (latest follows the main branch, and release tags such as X.Y and X.Y.Z are available for versioned deployments), TRELLO_MCP_HOST_BIND_IP defaults to 127.0.0.1 for local-only access, TRELLO_MCP_HOST_PORT defaults to 3000 and maps that host port to the container's fixed internal 3000 listener, while TRELLO_MCP_NETWORK defaults to trello-mcp_network. Set TRELLO_MCP_HOST_BIND_IP=0.0.0.0 only when you intentionally want Docker to publish the service on all host interfaces, such as for LAN access.

Set MCP_AUTH_TOKEN to require Authorization: Bearer on HTTP MCP requests to /mcp. Leave it unset for the default unauthenticated local behavior. Health and readiness endpoints remain unauthenticated for container and reverse-proxy checks.

Container health follows TRANSPORT: HTTP checks /healthz on PORT (default 3000), while stdio uses process liveness and lets the attached MCP client check protocol responsiveness. Compose inherits this image health check.

Keep the Trello rate-limit and retry values at their defaults unless logs show trello rate limit wait or trello request rate limited; retrying during large workflows. Lower the capacity for shared tokens or constrained deployments; raise it carefully only after narrowing the workflow's board, card, field, and pagination scope.

For repeatable deployments, select a release and pin its verified index digest. See image trust and read-only verification for SBOM/provenance inspection, the GHCR signing policy, and the separate Docker-built catalog path. Metadata integrity checks do not authenticate a publisher. Published Docker image tags use these conventions:

You can also run the published image directly without Compose:

docker run --rm -p 127.0.0.1:3000:3000 \

-e TRELLO_API_KEY=your-api-key \ -e TRELLO_TOKEN=your-token \ ghcr.io/enthouan/trello-mcp:latest

Option B: Build Locally from Source

Use this path if you want to develop the project, test local changes, or build the Docker image yourself.

Local development uses Node.js 24.x and the pinned pnpm@10.34.1 package manager through Corepack.

git clone https://github.com/enthouan/trello-mcp.git

cd trello-mcp cp .env.example .env

Edit .env with your Trello credentials, then build and run locally:

docker compose -f docker-compose.local.yml up --build -d --wait --wait-timeout 120

This uses docker-compose.local.yml, which builds from the local Dockerfile and tags the image as trello-mcp:local.

For a non-Docker local build:

corepack enable

corepack prepare pnpm@10.34.1 --activate corepack pnpm install --frozen-lockfile corepack pnpm build:clean

Then run the compiled server directly:

TRELLO_API_KEY=your-api-key TRELLO_TOKEN=your-token TRANSPORT=stdio node dist/index.js

Treat the token like a password. Do not commit it, paste it in logs, or share it in PRs.

3. Connect Your MCP Client

Choose the transport by where the server runs:

The Set up your MCP client guide has current, sanitized examples for Claude Desktop, Claude Code, Codex CLI, VS Code, OpenCode, MCP Inspector, and other manual clients. It also covers restart requirements, HTTP bearer support, secret handling, and tested limitations.

For dated client versions and evidence, see MCP Client Compatibility.

4. Verify

If you chose Streamable HTTP, check the server:

curl http://127.0.0.1:3000/healthz

curl http://127.0.0.1:3000/readyz

If you changed TRELLO_MCP_HOST_PORT, replace 3000 with that host port. If you changed TRELLO_MCP_HOST_BIND_IP from 127.0.0.1, use a hostname or IP address that can reach the bound host interface.

Then confirm the MCP client discovers the current 77-tool surface. With an intentional read-only credential check, call auth_whoami or auth_token_info from the client. Do not make a write-side Trello call just to prove setup.

Trello Credentials

This server currently uses Trello API key + token authentication. Follow the dedicated Trello API credentials guide for a security-focused walkthrough, with links to Trello's official App Admin Portal, authorization, and revocation documentation.

Use the read-only auth_whoami and auth_token_info tools to verify which Trello member the configured credentials authenticate as and to inspect the configured token's owner, expiration, and permissions. These tools are diagnostics only; this server does not implement OAuth redirects, token creation, token refresh, token revocation, or other token lifecycle management.

Set up your MCP client

Use the canonical [Set up you