Trello

io.github.scaratecPublished by GitHub account scaratecv0.12.0Updated Oct 24, 2026

MCP server for Trello — manage boards, lists, cards, attachments and more via Claude or Gemini

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & Storage

Overview

AI-generated overview

Lets an assistant read and manage Trello boards, lists, cards, checklists, comments, labels, attachments and webhooks through the Trello API.

What you can do
A local stdio MCP server exposing 48 tools that map one-to-one onto the Trello API, plus a composite get_board_overview tool. It covers boards, lists, cards, labels, checklists, comments, members, attachments and webhooks, including create, update, archive and delete operations. It also provides two resource templates for board and card context and three workflow prompts: summarize_board, create_sprint and daily_standup.
When to use it
Useful when an assistant should work directly with Trello content: reviewing or summarizing a board, drafting and updating cards, managing checklists and comments, or running sprint and standup workflows from a chat client.
Requirements
Python 3.10+ and a local install via pipx or pip. A Trello API key is required, and either an interactive browser authorization that stores credentials in a local credentials file, or the TRELLO_API_KEY and TRELLO_TOKEN environment variables as a fallback. The API key's allowed origins must include the local callback address. Network access to the Trello API is needed.
Before you install
The server holds Trello credentials: TRELLO_API_KEY and TRELLO_TOKEN, or a stored credentials file, and it can create, update, archive and delete boards, cards, lists, comments, labels, attachments and webhooks. Deletions and archives are destructive, so confirm intent before letting an assistant act. Attachment upload and download move files between the machine and Trello.

Installation

In SourceWeft

  1. Open Trello in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

trellio-mcp — MCP Server for Trello

[License: GPL v3] [Python 3.10+] [MCP]

An MCP server that gives Claude Desktop, Claude Code, and Gemini CLI full access to the Trello API. Built on the trellio async client library and the official Python MCP SDK. Developed following the BDD Guidelines v1.8.0.

Features

  • 48 MCP tools — 1:1 mapping to trellio methods, plus one composite get_board_overview tool
  • 2 resource templates — trello://board/{id} and trello://card/{id} for rich context loading
  • 3 prompts — summarize_board, create_sprint, daily_standup as workflow shortcuts
  • Built-in auth flow — python -m trello_mcp auth opens the browser, user clicks "Allow", token stored securely
  • Structured error handling — Trello API errors are translated into clear, actionable MCP error messages
  • stdio transport — runs as a local subprocess, no network surface

Tools

CategoryToolsCount
Discoverylist_boards, search2
Boardsget_board_overview, create_board, get_board, update_board, delete_board5
Listslist_lists, create_list, update_list, archive_list4
Cardslist_cards, create_card, get_card, update_card, archive_card, unarchive_card, delete_card, add_label_to_card, remove_label_from_card9
Labelslist_board_labels, create_label, update_label, delete_label4
Checklistslist_card_checklists, create_checklist, delete_checklist, create_check_item, update_check_item, delete_check_item6
Commentslist_comments, add_comment, update_comment, delete_comment4
Membersget_me, list_board_members, get_member3
Attachmentslist_attachments, create_attachment, get_attachment, upload_attachment, download_attachment, delete_attachment6
Webhookslist_webhooks, create_webhook, get_webhook, update_webhook, delete_webhook5

Card tools support pos (top/bottom), idLabels (comma-separated), due (ISO 8601), and dueComplete (true/false) on create and update.

Prerequisites

  • Python 3.10+
  • A Trello API Key (add http://localhost:8095 to Allowed Origins)

Installation

Using pipx (recommended)

To install globally so the trellio-mcp command is available in your PATH:

bash
pipx install trellio-mcp

Alternatively, you can run it on-the-fly without installing:

bash
pipx run trellio-mcp

(Note: If you use pipx run, your MCP client configuration must also use pipx as the command and run trellio-mcp as arguments.)

Using pip

bash
pip install trellio-mcp

From source

bash
git clone https://github.com/scaratec/trellio-mcp.gitcd trellio-mcppython3 -m venv .venv.venv/bin/pip install -e ".[dev]"

Authentication

Interactive (recommended)

Run the auth command on each machine to connect your Trello account:

If you installed globally (pipx install or pip install):

bash
TRELLO_API_KEY=your_api_key trellio-mcp auth

If using on-the-fly execution (pipx run):

bash
TRELLO_API_KEY=your_api_key pipx run trellio-mcp auth

This opens a browser where you authorize the app. The token is captured automatically and stored in ~/.config/trellio-mcp/credentials.json (permissions 0600).

After auth, no environment variables are needed — the server reads stored credentials on startup.

Environment Variables (fallback)

If no stored credentials are found, the server falls back to environment variables:

bash
export TRELLO_API_KEY=your_api_keyexport TRELLO_TOKEN=your_token

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json
{  "mcpServers": {    "trello": {      "command": "pipx",      "args": ["run", "trellio-mcp"]    }  }}

If using env var auth instead of stored credentials, add:

json
"env": {  "TRELLO_API_KEY": "your_api_key",  "TRELLO_TOKEN": "your_token"}

Claude Code

Add to ~/.claude/settings.json or project .claude/settings.json:

json
{  "mcpServers": {    "trello": {      "command": "pipx",      "args": ["run", "trellio-mcp"]    }  }}

Gemini CLI

Add to ~/.gemini/settings.json:

json
{  "mcpServers": {    "trello": {      "command": "pipx",      "args": ["run", "trellio-mcp"]    }  }}

Architecture

MCP Client (Claude / Gemini)    │ stdio (JSON-RPC)    ▼trellio-mcp (FastMCP)    │ async/await    ▼trellio (httpx)    │ HTTPS    ▼Trello API

Key decisions (documented in docs/adr/):

ADRDecision
001Python MCP SDK for language alignment with trellio
002stdio transport — no network attack surface
003Stored credentials with env var fallback
0041:1 tool mapping — one tool per trellio method
005trellio as PyPI dependency (>=1.4.0)
006Tools + Resources + Prompts as MCP capabilities
007isError=true + structured error content

Accepted weaknesses are recorded separately in docs/limitations/. A limitation there has already been weighed against the clean solution and declined — check the register before proposing a fix for a known-imperfect behaviour.

Testing

The project uses BDD with behave, following the BDD Guidelines v1.8.0.

bash
PYTHONPATH=src .venv/bin/python -m behave
18 features passed, 0 failed, 0 skipped182 scenarios passed, 0 failed, 0 skipped1103 steps passed, 0 failed, 0 skipped

dependency_compatibility.feature needs network access: it builds a wheel, installs it into throwaway environments at both ends of the declared mcp range, and drives the resulting server over stdio. It is the only feature that sees a broken dependency declaration — the others import the tool functions against the local .venv. It carries no opt-in tag on purpose: a dependency guard that has to be asked for is not a guard. To run the suite offline, exclude it explicitly:

bash
PYTHONPATH=src .venv/bin/python -m behave \  --exclude dependency_compatibility

Test architecture:

  • AsyncMock(spec=TrellioClient) — mock at the client boundary, not HTTP
  • Persistence validation via mock call records (§4.3)
  • Anti-hardcoding via Scenario Outlines with >= 2 variants (§2.3)
  • Layer-by-layer failure path enumeration (§4.5)
  • Independent spec audit per §13

See Case Study for a detailed account of the BDD-driven development process.

Project Structure

trellio-mcp/├── src/trello_mcp/│   ├── __init__.py        # Tool registration│   ├── __main__.py        # Entry point (server + auth)│   ├── server.py          # FastMCP instance + client mgmt│   ├── auth.py            # OAuth flow + credential storage│   ├── errors.py          # Error translation (ADR 007)│   ├── tools/             # 10 modules, 48 tools│   ├── resources.py       # 2 resource templates│   └── prompts.py         # 3 prompts├── features/              # 18 BDD feature files│   └── steps/             # Step definitions├── docs/│   ├── adr/               # 7 Architecture Decision Records│   ├── limitations/       # Limitation Records (accepted weaknesses)│   ├── tool-design.md     # Scenario-driven tool analysis│   └── case-study-bdd-mcp-server.md└── pyproject.toml

Publishing

PyPI

bash
uv buildtwine upload dist/trellio_mcp-<version>*

Smithery

Namespace is gupta. Update the release after a new PyPI version:

bash
npx @smithery/cli mcp publish "https://github.com/scaratec/trellio-mcp" -n gupta/trellio-mcp

Also update the pinned version in smithery.yaml commandFunction.

The resulting listing stays empty. Smithery populates an external entry by scanning the server over HTTP; this server is stdio-only (ADR 002), so the scan fails and the entry carries no connection or tool list — even though the publish command reports success. See LIM 0001. Install via pipx or uvx instead.

MCP registry

server.json describes the server for the official MCP registry by static declaration rather than introspection. Keep its two version fields in step with pyproject.toml.

License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.

Source: README.md at commit b9f2902

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.12.0LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.