trellio-mcp — MCP Server for Trello

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

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:

pipx install trellio-mcp

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

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

pip install trellio-mcp

From source

git clone https://github.com/scaratec/trellio-mcp.git
cd trellio-mcp
python3 -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):

TRELLO_API_KEY=your_api_key trellio-mcp auth

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

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:

export TRELLO_API_KEY=your_api_key
export 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):

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

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

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

Claude Code

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

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

Gemini CLI

Add to ~/.gemini/settings.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/):

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.

PYTHONPATH=src .venv/bin/python -m behave

18 features passed, 0 failed, 0 skipped
182 scenarios passed, 0 failed, 0 skipped
1103 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:

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

uv build
twine upload dist/trellio_mcp-<version>*

Smithery

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

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.