MCP Server Trello

Professional Model Context Protocol (MCP) server and local CLI for Trello. It exposes 23 typed tools for boards, lists, cards, checklists, activity, and workspace navigation, with Trello-aware rate limiting and validation built in.

This repository is maintained as ftaricano/mcp-server-trello. It is derived from MIT-licensed original work by Jarad DeLorenzo, with original copyright preserved and current ownership/provenance documented in NOTICE.md.

Highlights

• 23 MCP tools for cards, lists, boards, workspaces, checklists, attachments, and activity.
• Multi-board and workspace support with persisted active board/workspace state.
• Trello API rate limiting for the documented per-key and per-token limits.
• Zod input validation and TypeScript declarations in the published package.
• trello CLI for local agent workflows.
• CI on Node.js 20 and 22 for lint, typecheck, tests, build, and npm pack --dry-run.

Requirements

• Node.js 20 or newer.
• A Trello API key from https://trello.com/app-key.
• A Trello token created from that API key.

Install

Use the package directly from npm-compatible MCP clients:

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "@ftaricano/mcp-server-trello"],
      "env": {
        "TRELLO_API_KEY": "replace_with_trello_api_key",
        "TRELLO_TOKEN": "replace_with_trello_token"
      }
    }
  }
}

With pnpx:

{
  "mcpServers": {
    "trello": {
      "command": "pnpx",
      "args": ["@ftaricano/mcp-server-trello"],
      "env": {
        "TRELLO_API_KEY": "replace_with_trello_api_key",
        "TRELLO_TOKEN": "replace_with_trello_token"
      }
    }
  }
}

Global install is also supported:

npm install -g @ftaricano/mcp-server-trello
mcp-server-trello

Trello Token

Create a Trello token by visiting this URL after replacing the app name and API key:

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

Use expiration=30days or another shorter value when your operating model can tolerate periodic token renewal. Treat the token like a password.

Configuration

The server reads credentials from environment variables:

TRELLO_API_KEY=replace_with_trello_api_key
TRELLO_TOKEN=replace_with_trello_token

# Optional defaults. These can also be changed at runtime by MCP tools.
TRELLO_BOARD_ID=
TRELLO_WORKSPACE_ID=

The CLI also loads a .env file from the current working directory and can read credentials from the macOS Keychain when TRELLO_KEYCHAIN_PREFIX is set:

security add-generic-password -s TRELLO_API_KEY -a "$USER" -w "replace_with_trello_api_key"
security add-generic-password -s TRELLO_TOKEN -a "$USER" -w "replace_with_trello_token"

export TRELLO_KEYCHAIN_PREFIX=TRELLO
trello list-boards --md

Credential resolution order for the CLI:

1. Process environment.
2. .env file in the current working directory.
3. macOS Keychain entries named <PREFIX>_API_KEY, <PREFIX>_TOKEN, and optionally <PREFIX>_BOARD_ID.

Tools

Card tools:

• add_card_to_list
• update_card_details
• archive_card
• move_card
• get_card
• get_cards_by_list_id
• get_my_cards
• attach_image_to_card

List, board, and workspace tools:

• get_lists
• add_list_to_board
• archive_list
• list_boards
• set_active_board
• list_workspaces
• set_active_workspace
• list_boards_in_workspace
• get_active_board_info
• get_recent_activity

Checklist tools:

• get_checklist_items
• add_checklist_item
• find_checklist_items_by_description
• get_acceptance_criteria
• get_checklist_by_name

Most board-scoped tools accept an optional boardId. If omitted, the configured or persisted active board is used.

CLI

The package installs a trello binary for local agent and terminal workflows.

trello list-boards --md
trello set-board <boardId>
trello active-board --md
trello lists --md
trello board labels --md
trello board members --md

trello card add <listId> "Task name" --desc "details" --due 2026-05-01T12:00:00Z
trello card update <cardId> --name "Renamed" --done
trello card move <cardId> <listId>
trello card get <cardId> --md
trello card archive <cardId>
trello card comment <cardId> "Status update"
trello card attach <cardId> https://example.com/cover.png --name "Cover"
trello card assign <cardId> <memberId>
trello card unassign <cardId> <memberId>

trello cards mine --md
trello cards list <listId> --md

Default output is JSON for agent consumption. Add --md for markdown output. Exit codes are 0 for success, 1 for missing config or validation errors, and 2 for Trello API errors.

Date Formats

• dueDate: full ISO 8601 timestamp, for example 2026-05-01T12:00:00Z.
• start: date only, for example 2026-05-01.

Rate Limiting

Requests are queued through a token bucket limiter for Trello's published API limits:

• 300 requests per 10 seconds per API key.
• 100 requests per 10 seconds per token.

Development

git clone https://github.com/ftaricano/mcp-server-trello.git
cd mcp-server-trello
SKIP_PREPARE=true npm install
cp .env.example .env

Useful commands:

npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

Security

Do not commit real Trello credentials, .env files, local logs, generated databases, or machine-specific agent configuration. See SECURITY.md for supported reporting channels and credential rotation guidance.

Contributing

Before opening a PR, run:

npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

Keep changes focused and include tests for behavior changes.

Provenance

This project started as a fork of delorenj/mcp-server-trello. Credit for the original MCP server scaffolding, base Trello API integration, and initial tool surface belongs to Jarad DeLorenzo.

This repository is maintained under ftaricano/mcp-server-trello. Additions include the trello CLI binary, macOS Keychain credential resolution, expanded CLI card/board/list coverage, 152 unit tests, CI on Node.js 20/22, package metadata ownership, security documentation, and npm pack hardening.

See NOTICE.md for the provenance statement.

Acknowledgments

• Original MCP server by Jarad DeLorenzo (delorenj/mcp-server-trello)
• Built with the Model Context Protocol SDK
• Uses the Trello REST API

License

MIT. See LICENSE.