trello-mcp

A Codex-first Trello MCP server for AI agents

trello-mcp gives Codex and other MCP-compatible AI agents a clean, practical way to inspect and update Trello boards through Trello's official REST API.

Why This Exists

AI agents are useful when they can see the real workflow, not just the codebase. This server lets Codex connect to Trello so it can understand tasks, keep cards updated, add evidence comments, and help maintain project boards without scraping or browser automation.

It is designed for Codex first, but it works as a normal stdio MCP server in any client that supports the Model Context Protocol.

Related MCP server: Trello MCP Server

Features

Tool List

Quick Start

git clone https://github.com/KharalDipendra/trello-mcp.git
cd trello-mcp
npm install
npm run build

Run the local verification suite:

npm run check

Trello Credentials

You need a Trello API key and token.

1. Open Trello's API key page: trello.com/app-key

2. Copy your API key.

3. Generate a token using this URL after replacing YOUR_API_KEY:

https://trello.com/1/authorize?expiration=never&name=trello-mcp&scope=read,write&response_type=token&key=YOUR_API_KEY

Required environment variables:

TRELLO_API_KEY=your_trello_api_key
TRELLO_TOKEN=your_trello_token

Optional environment variables:

TRELLO_BOARD_ID=default_board_id
TRELLO_IDENTITY=default
TRELLO_BASE_URL=https://api.trello.com/1

Never commit a real .env file. Keep Trello credentials in your MCP client config, shell environment, or secret manager.

Codex Setup

Build the project first:

npm install
npm run build

Then add an MCP server entry to your Codex config:

{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["/absolute/path/to/trello-mcp/dist/index.js"],
      "env": {
        "TRELLO_API_KEY": "your_trello_api_key",
        "TRELLO_TOKEN": "your_trello_token",
        "TRELLO_BOARD_ID": "optional_default_board_id",
        "TRELLO_IDENTITY": "default"
      }
    }
  }
}

For Windows paths, use escaped backslashes or forward slashes:

"args": ["C:/Users/you/Desktop/trello-mcp/dist/index.js"]

Multiple Trello Accounts

Run one MCP entry per Trello identity:

{
  "mcpServers": {
    "trello-personal": {
      "command": "node",
      "args": ["/absolute/path/to/trello-mcp/dist/index.js"],
      "env": {
        "TRELLO_API_KEY": "key_for_account_one",
        "TRELLO_TOKEN": "token_for_account_one",
        "TRELLO_IDENTITY": "account-one"
      }
    },
    "trello-work": {
      "command": "node",
      "args": ["/absolute/path/to/trello-mcp/dist/index.js"],
      "env": {
        "TRELLO_API_KEY": "key_for_account_two",
        "TRELLO_TOKEN": "token_for_account_two",
        "TRELLO_IDENTITY": "account-two"
      }
    }
  }
}

Standalone MCP Usage

The server communicates over stdio, so it is normally launched by an MCP client.

TRELLO_API_KEY=... TRELLO_TOKEN=... node dist/index.js

You can also run the TypeScript source during development:

TRELLO_API_KEY=... TRELLO_TOKEN=... npm run dev

Agent Safety Model

trello-mcp is intentionally simple and explicit:

• It uses Trello's REST API directly.

• It does not scrape Trello pages.

• It does not store credentials.

• It redacts credentials from Trello API error messages.

• It exposes archive tools, not permanent delete tools.

• It encourages agents to inspect board state before changing cards.

Recommended agent behaviour:

1. Read the board, lists, and relevant cards first.

2. Explain planned changes before writing when the workflow is sensitive.

3. Add short evidence comments for meaningful card updates.

4. Move cards to done only when the underlying work is actually complete.

5. Prefer archiving stale cards over deleting them.

Development

npm install
npm run check

Available scripts:

The test suite uses mocked Trello responses and does not call the live Trello API.

Project Structure

trello-mcp/
  examples/
    codex-mcp.json
  src/
    index.ts
    trelloClient.ts
  test/
    trelloClient.test.ts

Contributing

Issues and pull requests are welcome. Keep changes generic and avoid committing board data, workspace names, real card content, tokens, or account-specific config.

License

MIT. See LICENSE.