<div align="center">

# trello-mcp

### A Codex-first Trello MCP server for AI agents

[![Codex ready](https://img.shields.io/badge/Codex-ready-111827?style=for-the-badge&logo=openai&logoColor=white)](https://github.com/KharalDipendra/trello-mcp)
[![MCP server](https://img.shields.io/badge/MCP-server-2563eb?style=for-the-badge)](https://modelcontextprotocol.io/)
[![Trello](https://img.shields.io/badge/Trello-integration-0052cc?style=for-the-badge&logo=trello&logoColor=white)](https://trello.com/)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-f59e0b?style=for-the-badge)](LICENSE)

`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

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

Run the local verification suite:

```bash
npm run check
```

## Trello Credentials

You need a Trello API key and token.

1. Open Trello's API key page: [trello.com/app-key](https://trello.com/app-key)
2. Copy your API key.
3. Generate a token using this URL after replacing `YOUR_API_KEY`:

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

Required environment variables:

```bash
TRELLO_API_KEY=your_trello_api_key
TRELLO_TOKEN=your_trello_token
```

Optional environment variables:

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

```bash
npm install
npm run build
```

Then add an MCP server entry to your Codex config:

```json
{
  "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:

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

## Multiple Trello Accounts

Run one MCP entry per Trello identity:

```json
{
  "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.

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

You can also run the TypeScript source during development:

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

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

```text
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](LICENSE).