Skip to main content
Glama

mcp-trello

CI License: MIT Node.js MCP

Model Context Protocol (MCP) server and local CLI for Trello. It exposes 31 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-trello (formerly 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

  • 31 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.

Related MCP server: Trello MCP Server

Requirements

Install

Use the package directly from npm-compatible MCP clients:

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "@ftaricano/mcp-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-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-trello
mcp-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-trello.git
cd mcp-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-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

License

MIT. See LICENSE.

Available Tools

31 tools
add_card_to_listAdd Card to ListA

Add a new card to a specified list on a specific board

Inputs: name (required), listId (required), start, labels, +3 more.

add_checklist_itemAdd Checklist ItemC

Add a new item to a checklist

Inputs: text (required), checkListName (required), boardId.

add_commentAdd CommentA

Add a comment to a card

Inputs: text (required), cardId (required).

add_list_to_boardAdd List to BoardB

Add a new list to the specified board

Inputs: name (required), boardId.

archive_cardArchive CardB

Send a card to the archive on a specific board

Inputs: cardId (required), boardId.

archive_listArchive ListB

Send a list to the archive on a specific board

Inputs: listId (required), boardId.

assign_memberAssign MemberB

Assign a member to a card

Inputs: cardId (required), memberId (required).

attach_image_to_cardAttach Image to CardA

Attach an image (or any file) to a card from a URL on a specific board

Inputs: cardId (required), imageUrl (required), name, boardId.

delete_attachmentDelete AttachmentB

Remove an attachment from a card

Inputs: cardId (required), attachmentId (required).

download_attachmentDownload AttachmentA

Download the binary content of a card attachment. Trello-hosted attachments on private boards require authentication that a plain URL fetch lacks (401) — this tool sends the correct credentials. Returns an image block for images, otherwise base64 + metadata.

Inputs: cardId (required), attachmentId (required), maxBytes.

find_checklist_items_by_descriptionFind Checklist Items by DescriptionC

Search for checklist items containing specific text in their description

Inputs: description (required), boardId.

get_acceptance_criteriaGet Acceptance CriteriaB

Get all items from the "Acceptance Criteria" checklist

Inputs: boardId.

get_active_board_infoGet Active Board InfoB

Get information about the currently active board

Inputs: no named parameters.

get_board_labelsGet Board LabelsA

List all labels defined on a board

Inputs: boardId.

get_board_membersGet Board MembersA

List all members of a board

Inputs: boardId.

get_cardGet CardA

Get detailed information about a specific Trello card

Inputs: cardId (required), includeMarkdown.

get_card_attachmentsGet Card AttachmentsA

List all attachments on a card (metadata: id, name, url, fileName, mimeType, bytes). Use download_attachment to fetch the actual file content.

Inputs: cardId (required).

get_cards_by_list_idGet Cards by List IDB

Fetch cards from a specific Trello list on a specific board

Inputs: listId (required), boardId.

get_checklist_by_nameGet Checklist by NameA

Get a complete checklist with all its items and completion percentage

Inputs: name (required), boardId.

get_checklist_itemsGet Checklist ItemsA

Get all items from a checklist by name

Inputs: name (required), boardId.

get_listsGet ListsA

Retrieve all lists from the specified board

Inputs: boardId.

get_my_cardsGet My CardsA

Fetch all cards assigned to the current user

Inputs: no named parameters.

get_recent_activityGet Recent ActivityB

Fetch recent activity on the Trello board

Inputs: limit, boardId.

list_boardsList BoardsA

List all boards the user has access to

Inputs: no named parameters.

list_boards_in_workspaceList Boards in WorkspaceA

List all boards in a specific workspace

Inputs: workspaceId (required).

list_workspacesList WorkspacesA

List all workspaces the user has access to

Inputs: no named parameters.

move_cardMove CardB

Move a card to a different list, potentially on a different board

Inputs: cardId (required), listId (required), boardId.

set_active_boardSet Active BoardA

Set the active board for future operations

Inputs: boardId (required).

set_active_workspaceSet Active WorkspaceA

Set the active workspace for future operations

Inputs: workspaceId (required).

unassign_memberUnassign MemberA

Remove a member from a card

Inputs: cardId (required), memberId (required).

update_card_detailsUpdate Card DetailsB

Update an existing card's details on a specific board

Inputs: cardId (required), name, start, labels, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 31 tools

    Disambiguation3/5

    Most tools have distinct resource-action pairs, but the checklist retrieval cluster (get_checklist_items, get_checklist_by_name, get_acceptance_criteria) overlaps significantly, and list_boards vs list_boards_in_workspace adds minor confusion. Descriptions help but boundaries are not always clear.

    Naming Consistency5/5

    All tool names consistently use snake_case with verb-first patterns (add_, get_, list_, set_, etc.). The naming convention is uniform and predictable across all 31 tools.

    Tool Count2/5

    31 tools is above the 25-tool threshold and includes several redundant checklist retrieval tools and overlapping board-listing tools. The count feels excessive for the actual distinct operations offered.

    Completeness2/5

    The surface covers many card, list, and attachment operations, but lacks board creation/deletion, label assignment, comment retrieval, checklist creation, and card deletion (only archive). These gaps will force agents to work around missing functionality.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers