trello-mcp

# trello-mcp

A self-hostable [Model Context Protocol](https://modelcontextprotocol.io/) server that lets MCP-compatible clients work with [Trello](https://trello.com/) 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](https://trello.com/b/GnKmvuHz/trello-mcp-enthouan-trello-mcp).

## 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](https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/) and user-provided API credentials.

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

## Documentation

The complete project documentation is available at [trello-mcp.com](https://trello-mcp.com/):

- [Get started](https://trello-mcp.com/getting-started/)
- [Create a Trello API key and token](https://trello-mcp.com/getting-started/trello-api-key/)
- [Set up your MCP client](https://trello-mcp.com/getting-started/clients/)
- [Browse the tool catalog](https://trello-mcp.com/reference/tools/)
- [Review API coverage and non-goals](https://trello-mcp.com/reference/api-coverage/)
- [Understand Security & Data](https://trello-mcp.com/guides/security/)
- [Operate a running deployment](https://trello-mcp.com/guides/operations/)
- [Troubleshoot an installation](https://trello-mcp.com/guides/troubleshooting/)
- [Official MCP Registry installation, releases, and recovery](docs/mcp-registry.md)

## 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 by natural language terms.
- 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](docs/trello-api-key.md) for the current, security-focused walkthrough.

In short: create or select an app at [trello.com/apps/admin](https://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:

```bash
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.

```bash
git clone https://github.com/enthouan/trello-mcp.git
cd trello-mcp
cp .env.example .env
```

Edit `.env` and replace the placeholder values:

```bash
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:

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

The default `docker-compose.yml` uses:

```text
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 <token>` 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 reproducible deployments, prefer an exact `X.Y.Z` tag. Published Docker
image tags use these conventions:

| Tag | Use case |
| --- | --- |
| `latest` | Follows the current `main` branch build. Use it when you intentionally want the newest main-branch image. |
| `X.Y` | Follows the newest patch release in a minor line, moving to the image built from the latest matching `vX.Y.Z` tag. |
| `X.Y.Z` | Pins to one exact release. Use this for the most reproducible deployments. |
| `sha-<commit>` | Pins to one exact commit image from the release workflow. Use this for debugging or audit trails. |

You can also run the published image directly without Compose:

```bash
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.

```bash
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:

```bash
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:

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

Then run the compiled server directly:

```bash
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:

| Your setup | Choose | Client receives |
| --- | --- | --- |
| A built clone and the MCP client are on the same machine | `stdio` | A local command plus Trello credentials in the child-process environment |
| The server runs in Docker, behind a reverse proxy, or on another host | Streamable HTTP | An `/mcp` URL plus an optional bearer token; Trello credentials stay on the server |

The [Set up your MCP client guide](docs/client-setup.md) has current, sanitized
examples for Claude Desktop, Claude Code, Codex CLI, VS Code, OpenCode, MCP
Inspector