Install and run

Independent integration for Trello

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.

Looking for Trello’s official MCP server? Visit Trello MCP.

Start with the smallest deployment shape that fits where your MCP client runs. Local stdio opens no network listener. Docker Compose and Streamable HTTP provide a persistent service when you need one.

Prerequisites

• A Trello account with an API key and token.
• Docker with Docker Compose, or Node.js 24.x with the repository’s pinned pnpm version.
• An MCP client that supports Streamable HTTP or stdio.

Treat the Trello token like a password

TRELLO_TOKEN can read and change resources visible to the member who authorized it. Keep both Trello credentials in a private client configuration, ignored .env, or deployment secret, and revoke the token at Trello if it leaks.

Common path

1. Create the Trello credentials. Create an API key and token, then keep TRELLO_API_KEY and TRELLO_TOKEN in an ignored .env, client secret store, or deployment secret.

2. Build or start the server. Use local stdio for a client-launched process, the published Docker Compose service for a persistent installation, or the local Compose build when you want to run checked-out source over HTTP.

3. Configure the MCP client. For stdio, use an absolute path to the built dist/index.js. For Streamable HTTP, point the client at the running /mcp endpoint and add its separate bearer token when MCP_AUTH_TOKEN is configured.

4. Restart and verify. Restart the client, confirm that it discovers the trello-mcp tools, then review and approve only the supplied read-only auth_whoami call. Health endpoints alone verify the process, not the complete MCP and Trello path.

Protect Streamable HTTP

Keep Docker Compose published to 127.0.0.1 for same-machine use. If you deliberately make it reachable from a network, add MCP_AUTH_TOKEN, HTTPS, and suitable network access controls.

Choose a transport, then an installation

First choose the trust boundary between the MCP client and trello-mcp. Both transports expose the same tool catalog.

Transport	Choose it when	Server shape
Local stdio	The MCP client and a built checkout run on the same machine. The client launches the server as a child process, and no network listener opens.	Build the source once, then configure the client with absolute executable and entry paths.
Streamable HTTP	The server should run continuously or serve a separately managed client.	Prefer the published image with an exact X.Y.Z tag. Build the image locally when you specifically want to run checked-out source.

The copy-paste shell commands below are labeled for macOS/Linux. Windows users can use WSL2 or the PowerShell commands in the detailed HTTP guides. The stdio build commands work in PowerShell as written.

Local stdio

Cross-platform MCP client process configuration

{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["/absolute/path/to/trello-mcp/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "TRELLO_API_KEY": "replace-with-your-api-key",
        "TRELLO_TOKEN": "replace-with-your-token"
      }
    }
  }
}

Build the checkout first. Stdio opens no network listener and does not use MCP_AUTH_TOKEN; keep the client configuration private because it contains the Trello credentials.

Read the complete Local stdio guide →

HTTP · published image

macOS/Linux — published image with Docker Compose

git clone https://github.com/enthouan/trello-mcp.git
cd trello-mcp
cp .env.example .env
# Set both Trello credentials and an available exact X.Y.Z image tag in .env
${EDITOR:-vi} .env
grep -Eq '^TRELLO_API_KEY=.+$' .env && ! grep -Eq '^TRELLO_API_KEY=replace-me$' .env || { echo 'Set TRELLO_API_KEY to a non-placeholder value in .env before starting.' >&2; exit 1; }
grep -Eq '^TRELLO_TOKEN=.+$' .env && ! grep -Eq '^TRELLO_TOKEN=replace-me$' .env || { echo 'Set TRELLO_TOKEN to a non-placeholder value in .env before starting.' >&2; exit 1; }
grep -Eq '^TRELLO_MCP_IMAGE_TAG=[0-9]+\.[0-9]+\.[0-9]+$' .env || { echo 'Set TRELLO_MCP_IMAGE_TAG to an exact published X.Y.Z release before starting.' >&2; exit 1; }
docker compose up -d --wait --wait-timeout 120
docker compose ps
curl -fsS http://127.0.0.1:3000/healthz
curl -fsS http://127.0.0.1:3000/readyz

The published image is ghcr.io/enthouan/trello-mcp. Compose publishes only to 127.0.0.1 by default; configure MCP_AUTH_TOKEN whenever a client should also present a separate server bearer token.

Read the complete HTTP · published image guide →

HTTP · source build

macOS/Linux — source-built HTTP on Docker loopback

git clone https://github.com/enthouan/trello-mcp.git
cd trello-mcp
cp .env.example .env
# Set TRELLO_API_KEY and TRELLO_TOKEN in .env
${EDITOR:-vi} .env
grep -Eq '^TRELLO_API_KEY=.+$' .env && ! grep -Eq '^TRELLO_API_KEY=replace-me$' .env || { echo 'Set TRELLO_API_KEY to a non-placeholder value in .env before starting.' >&2; exit 1; }
grep -Eq '^TRELLO_TOKEN=.+$' .env && ! grep -Eq '^TRELLO_TOKEN=replace-me$' .env || { echo 'Set TRELLO_TOKEN to a non-placeholder value in .env before starting.' >&2; exit 1; }
docker compose -f docker-compose.local.yml up --build -d --wait --wait-timeout 120
curl -fsS http://127.0.0.1:3000/healthz
curl -fsS http://127.0.0.1:3000/readyz

Connect to http://127.0.0.1:3000/mcp. The local Compose file builds the checkout and keeps the host publication on loopback by default.

Read the complete HTTP · source build guide →

Configure your client

The five quick recipes below configure Codex, Claude Code, Claude Desktop, VS Code, or OpenCode for local stdio. If you chose Streamable HTTP, use the complete client setup guide and select that transport for your client. For MCP Inspector and other clients, use the manual-client guidance.

Codex

Codex reads MCP servers from TOML and can forward already exported credentials without writing their values into the configuration file.

Where to configure it: Add these tables to ~/.codex/config.toml.

~/.codex/config.toml

[mcp_servers.trello]
command = "node"
args = ["/absolute/path/to/trello-mcp/dist/index.js"]
env_vars = ["TRELLO_API_KEY", "TRELLO_TOKEN"]

[mcp_servers.trello.env]
TRANSPORT = "stdio"

Protect the Trello credentials

Export TRELLO_API_KEY and TRELLO_TOKEN before launching Codex. env_vars forwards them to the child process without storing their values in TOML.

Reload the client: Start a new Codex session, then run codex mcp list or use /mcp to confirm that trello is connected.

Configuration syntax: Codex MCP documentation.

Verify it works

After the client discovers the server, review and approve only this named read-only call:

Read-only verification prompt

Which Trello account is connected? Use auth_whoami and do not change anything.

Expected result

Review the proposed call and approve only auth_whoami. It has no required inputs, is read-only, and returns the authenticated Trello member without changing Trello. That account metadata still passes through the MCP client and its configured model.

Sanitized example response

{
  "id": "member-id",
  "username": "your-username",
  "fullName": "Your Name"
}

Claude Code

Claude Code expands environment-variable references in a project-scoped .mcp.json file, so the shared file can avoid containing the Trello credentials.

Where to configure it: Export TRELLO_MCP_ROOT, TRELLO_API_KEY, and TRELLO_TOKEN, then create .mcp.json at the project root.

.mcp.json

{
  "mcpServers": {
    "trello": {
      "type": "stdio",
      "command": "node",
      "args": ["${TRELLO_MCP_ROOT}/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "TRELLO_API_KEY": "${TRELLO_API_KEY}",
        "TRELLO_TOKEN": "${TRELLO_TOKEN}"
      }
    }
  }
}

Protect the Trello credentials

The file contains only environment-variable references and can be shared after review. Keep the environment source for both Trello credentials private.

Reload the client: Start a new Claude Code session, run /mcp, and confirm that trello is connected. claude mcp list also reports connection status.

Configuration syntax: Claude Code MCP documentation.

Verify it works

After the client discovers the server, review and approve only this named read-only call:

Read-only verification prompt

Which Trello account is connected? Use auth_whoami and do not change anything.

Expected result

Review the proposed call and approve only auth_whoami. It has no required inputs, is read-only, and returns the authenticated Trello member without changing Trello. That account metadata still passes through the MCP client and its configured model.

Sanitized example response

{
  "id": "member-id",
  "username": "your-username",
  "fullName": "Your Name"
}

Claude Desktop

trello-mcp does not yet ship an MCPB desktop extension, so Claude Desktop launches the locally built server as a developer-defined stdio process.

Where to configure it: Open Settings → Developer → Edit Config and merge this entry into claude_desktop_config.json.

claude_desktop_config.json

{
  "mcpServers": {
    "trello": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/trello-mcp/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "TRELLO_API_KEY": "replace-in-this-user-local-file",
        "TRELLO_TOKEN": "replace-in-this-user-local-file"
      }
    }
  }
}

Protect the Trello credentials

This user-local file contains both Trello credentials in plaintext. Restrict access to it and never copy it into the repository or a support request.

Reload the client: Fully quit and reopen Claude Desktop, then inspect Connectors or Developer settings for the trello server and its tools.

Configuration syntax: MCP local-server guide.

Verify it works

After the client discovers the server, review and approve only this named read-only call:

Read-only verification prompt

Which Trello account is connected? Use auth_whoami and do not change anything.

Expected result

Review the proposed call and approve only auth_whoami. It has no required inputs, is read-only, and returns the authenticated Trello member without changing Trello. That account metadata still passes through the MCP client and its configured model.

Sanitized example response

{
  "id": "member-id",
  "username": "your-username",
  "fullName": "Your Name"
}

VS Code

VS Code password inputs can request both Trello credentials when the server first starts without placing their values directly in mcp.json.

Where to configure it: Run MCP: Open User Configuration from the Command Palette and merge these inputs and server entries.

User profile mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "trello-api-key",
      "description": "Trello API key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "trello-token",
      "description": "Trello token",
      "password": true
    }
  ],
  "servers": {
    "trello": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/trello-mcp/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "TRELLO_API_KEY": "${input:trello-api-key}",
        "TRELLO_TOKEN": "${input:trello-token}"
      }
    }
  }
}

Protect the Trello credentials

Password inputs keep both credential values out of mcp.json. These inputs target desktop VS Code; use private environment values for Agent Host portability.

Reload the client: Run MCP: List Servers, select trello, and start or restart it. Review the configuration before accepting VS Code's trust prompt.

Configuration syntax: VS Code MCP configuration reference.

Verify it works

After the client discovers the server, review and approve only this named read-only call:

Read-only verification prompt

Which Trello account is connected? Use auth_whoami and do not change anything.

Expected result

Review the proposed call and approve only auth_whoami. It has no required inputs, is read-only, and returns the authenticated Trello member without changing Trello. That account metadata still passes through the MCP client and its configured model.

Sanitized example response

{
  "id": "member-id",
  "username": "your-username",
  "fullName": "Your Name"
}

OpenCode

OpenCode defines local servers under mcp.servers and can read Trello credentials from the environment instead of a tracked project file.

Where to configure it: Save this as opencode.json in the project or ~/.config/opencode/opencode.json for global use.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "trello": {
        "type": "local",
        "command": [
          "node",
          "/absolute/path/to/trello-mcp/dist/index.js"
        ],
        "environment": {
          "TRANSPORT": "stdio",
          "TRELLO_API_KEY": "{env:TRELLO_API_KEY}",
          "TRELLO_TOKEN": "{env:TRELLO_TOKEN}"
        }
      }
    }
  }
}

Protect the Trello credentials

Keep the environment that supplies TRELLO_API_KEY and TRELLO_TOKEN private. This recipe was documentation-reviewed and syntax-checked, not directly run.

Reload the client: Relaunch OpenCode and run opencode2 mcp list. OpenCode does not currently promise hot reload after direct configuration edits.

Configuration syntax: OpenCode MCP documentation.

Verify it works

After the client discovers the server, review and approve only this named read-only call:

Read-only verification prompt

Which Trello account is connected? Use auth_whoami and do not change anything.

Expected result

Review the proposed call and approve only auth_whoami. It has no required inputs, is read-only, and returns the authenticated Trello member without changing Trello. That account metadata still passes through the MCP client and its configured model.

Sanitized example response

{
  "id": "member-id",
  "username": "your-username",
  "fullName": "Your Name"
}

The recipes reflect the current client setup guide and its documented evidence. They are not all represented as live compatibility tests. See the compatibility record for the exact client versions, transports, and test boundaries.

Next

• Docker Compose for the published-image operator path and tag guidance.
• Streamable HTTP for the endpoint, local source-build route, and network boundary.
• stdio for desktop and local MCP clients.
• Trello API key before configuring an installation.
• Set up your MCP client for the full recipes and current official-documentation links.
• Security and data flow before widening network access.
• Operate trello-mcp for upgrades, rollbacks, logs, and credential rotation.