<div align="center">

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.

</div>

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.

Features

Area	Supported actions
Account	Identify the authenticated Trello member
Workspaces	List visible Trello workspaces
Boards	List open boards and inspect board metadata
Lists	List board columns/lists
Cards	List, read, search, create, update, move, comment on, and archive cards
Checklists	Create checklists and checklist items
Agent safety	Redacted errors, no committed credentials, archive-first workflow guidance

Tool List

Tool	Purpose
trello_whoami	Show the authenticated Trello member
trello_list_workspaces	List visible Trello workspaces
trello_list_boards	List open Trello boards
trello_get_board	Read board metadata
trello_list_lists	List board lists
trello_list_cards	List cards, optionally by list
trello_get_card	Read a card
trello_search_cards	Search cards by text
trello_create_card	Create a card
trello_update_card	Update card title, description, due date, or archive state
trello_move_card	Move a card to another list
trello_add_comment	Add a card comment
trello_archive_card	Archive a card
trello_add_checklist	Add a checklist to a card
trello_add_check_item	Add an item to a checklist

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:

Script	Description
npm run build	Compile TypeScript into dist/
npm test	Run mocked client tests
npm run check	Build and test
npm run dev	Run the MCP server from TypeScript
npm start	Run the compiled MCP server

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.