{
  "markdown": "# trellio-mcp — MCP Server for Trello\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](https://modelcontextprotocol.io)\n\n<!-- mcp-name: io.github.scaratec/trellio-mcp -->\n\nAn MCP server that gives Claude Desktop, Claude Code, and\nGemini CLI full access to the Trello API. Built on the\n[trellio](https://github.com/scaratec/trellio) async client\nlibrary and the official Python MCP SDK. Developed following\nthe [BDD Guidelines v1.8.0](https://github.com/scaratec/burn-your-code).\n\n## Features\n\n- **48 MCP tools** — 1:1 mapping to trellio methods, plus\n  one composite `get_board_overview` tool\n- **2 resource templates** — `trello://board/{id}` and\n  `trello://card/{id}` for rich context loading\n- **3 prompts** — `summarize_board`, `create_sprint`,\n  `daily_standup` as workflow shortcuts\n- **Built-in auth flow** — `python -m trello_mcp auth` opens\n  the browser, user clicks \"Allow\", token stored securely\n- **Structured error handling** — Trello API errors are\n  translated into clear, actionable MCP error messages\n- **stdio transport** — runs as a local subprocess, no\n  network surface\n\n## Tools\n\n| Category    | Tools | Count |\n|-------------|-------|-------|\n| Discovery   | `list_boards`, `search` | 2 |\n| Boards      | `get_board_overview`, `create_board`, `get_board`, `update_board`, `delete_board` | 5 |\n| Lists       | `list_lists`, `create_list`, `update_list`, `archive_list` | 4 |\n| Cards       | `list_cards`, `create_card`, `get_card`, `update_card`, `archive_card`, `unarchive_card`, `delete_card`, `add_label_to_card`, `remove_label_from_card` | 9 |\n| Labels      | `list_board_labels`, `create_label`, `update_label`, `delete_label` | 4 |\n| Checklists  | `list_card_checklists`, `create_checklist`, `delete_checklist`, `create_check_item`, `update_check_item`, `delete_check_item` | 6 |\n| Comments    | `list_comments`, `add_comment`, `update_comment`, `delete_comment` | 4 |\n| Members     | `get_me`, `list_board_members`, `get_member` | 3 |\n| Attachments | `list_attachments`, `create_attachment`, `get_attachment`, `upload_attachment`, `download_attachment`, `delete_attachment` | 6 |\n| Webhooks    | `list_webhooks`, `create_webhook`, `get_webhook`, `update_webhook`, `delete_webhook` | 5 |\n\nCard tools support `pos` (top/bottom), `idLabels`\n(comma-separated), `due` (ISO 8601), and `dueComplete`\n(true/false) on create and update.\n\n## Prerequisites\n\n- Python 3.10+\n- A [Trello API Key](https://trello.com/power-ups/admin)\n  (add `http://localhost:8095` to Allowed Origins)\n\n## Installation\n\n### Using pipx (recommended)\n\nTo install globally so the `trellio-mcp` command is available in your PATH:\n\n```bash\npipx install trellio-mcp\n```\n\nAlternatively, you can run it on-the-fly without installing:\n\n```bash\npipx run trellio-mcp\n```\n*(Note: If you use `pipx run`, your MCP client configuration must also use `pipx` as the command and `run trellio-mcp` as arguments.)*\n\n### Using pip\n\n```bash\npip install trellio-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/scaratec/trellio-mcp.git\ncd trellio-mcp\npython3 -m venv .venv\n.venv/bin/pip install -e \".[dev]\"\n```\n\n## Authentication\n\n### Interactive (recommended)\n\nRun the auth command on each machine to connect your Trello account:\n\nIf you installed globally (`pipx install` or `pip install`):\n```bash\nTRELLO_API_KEY=your_api_key trellio-mcp auth\n```\n\nIf using on-the-fly execution (`pipx run`):\n```bash\nTRELLO_API_KEY=your_api_key pipx run trellio-mcp auth\n```\n\nThis opens a browser where you authorize the app. The token\nis captured automatically and stored in\n`~/.config/trellio-mcp/credentials.json` (permissions 0600).\n\nAfter auth, no environment variables are needed — the server\nreads stored credentials on startup.\n\n### Environment Variables (fallback)\n\nIf no stored credentials are found, the server falls back to\nenvironment variables:\n\n```bash\nexport TRELLO_API_KEY=your_api_key\nexport TRELLO_TOKEN=your_token\n```\n\n## MCP Client Configuration\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`\n(macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json`\n(Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"trello\": {\n      \"command\": \"pipx\",\n      \"args\": [\"run\", \"trellio-mcp\"]\n    }\n  }\n}\n```\n\nIf using env var auth instead of stored credentials, add:\n\n```json\n\"env\": {\n  \"TRELLO_API_KEY\": \"your_api_key\",\n  \"TRELLO_TOKEN\": \"your_token\"\n}\n```\n\n### Claude Code\n\nAdd to `~/.claude/settings.json` or project\n`.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"trello\": {\n      \"command\": \"pipx\",\n      \"args\": [\"run\", \"trellio-mcp\"]\n    }\n  }\n}\n```\n\n### Gemini CLI\n\nAdd to `~/.gemini/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"trello\": {\n      \"command\": \"pipx\",\n      \"args\": [\"run\", \"trellio-mcp\"]\n    }\n  }\n}\n```\n\n## Architecture\n\n```\nMCP Client (Claude / Gemini)\n    │ stdio (JSON-RPC)\n    ▼\ntrellio-mcp (FastMCP)\n    │ async/await\n    ▼\ntrellio (httpx)\n    │ HTTPS\n    ▼\nTrello API\n```\n\n**Key decisions** (documented in `docs/adr/`):\n\n| ADR | Decision |\n|-----|----------|\n| 001 | Python MCP SDK for language alignment with trellio |\n| 002 | stdio transport — no network attack surface |\n| 003 | Stored credentials with env var fallback |\n| 004 | 1:1 tool mapping — one tool per trellio method |\n| 005 | trellio as PyPI dependency (>=1.4.0) |\n| 006 | Tools + Resources + Prompts as MCP capabilities |\n| 007 | `isError=true` + structured error content |\n\n**Accepted weaknesses** are recorded separately in\n[`docs/limitations/`](docs/limitations/). A limitation there has\nalready been weighed against the clean solution and declined — check\nthe register before proposing a fix for a known-imperfect behaviour.\n\n## Testing\n\nThe project uses BDD with\n[behave](https://behave.readthedocs.io/), following the\n[BDD Guidelines v1.8.0](https://github.com/scaratec/burn-your-code).\n\n```bash\nPYTHONPATH=src .venv/bin/python -m behave\n```\n\n```\n18 features passed, 0 failed, 0 skipped\n182 scenarios passed, 0 failed, 0 skipped\n1103 steps passed, 0 failed, 0 skipped\n```\n\n`dependency_compatibility.feature` needs network access: it\nbuilds a wheel, installs it into throwaway environments at\nboth ends of the declared `mcp` range, and drives the\nresulting server over stdio. It is the only feature that\nsees a broken dependency declaration — the others import\nthe tool functions against the local `.venv`. It carries no\nopt-in tag on purpose: a dependency guard that has to be\nasked for is not a guard. To run the suite offline, exclude\nit explicitly:\n\n```bash\nPYTHONPATH=src .venv/bin/python -m behave \\\n  --exclude dependency_compatibility\n```\n\nTest architecture:\n- `AsyncMock(spec=TrellioClient)` — mock at the client\n  boundary, not HTTP\n- Persistence validation via mock call records (§4.3)\n- Anti-hardcoding via Scenario Outlines with >= 2 variants\n  (§2.3)\n- Layer-by-layer failure path enumeration (§4.5)\n- Independent spec audit per §13\n\nSee [Case Study](docs/case-study-bdd-mcp-server.md) for a\ndetailed account of the BDD-driven development process.\n\n## Project Structure\n\n```\ntrellio-mcp/\n├── src/trello_mcp/\n│   ├── __init__.py        # Tool registration\n│   ├── __main__.py        # Entry point (server + auth)\n│   ├── server.py          # FastMCP instance + client mgmt\n│   ├── auth.py            # OAuth flow + credential storage\n│   ├── errors.py          # Error translation (ADR 007)\n│   ├── tools/             # 10 modules, 48 tools\n│   ├── resources.py       # 2 resource templates\n│   └── prompts.py         # 3 prompts\n├── features/              # 18 BDD feature files\n│   └── steps/             # Step definitions\n├── docs/\n│   ├── adr/               # 7 Architecture Decision Records\n│   ├── limitations/       # Limitation Records (accepted weaknesses)\n│   ├── tool-design.md     # Scenario-driven tool analysis\n│   └── case-study-bdd-mcp-server.md\n└── pyproject.toml\n```\n\n## Publishing\n\n### PyPI\n\n```bash\nuv build\ntwine upload dist/trellio_mcp-<version>*\n```\n\n### Smithery\n\nNamespace is `gupta`. Update the release after a new PyPI version:\n\n```bash\nnpx @smithery/cli mcp publish \"https://github.com/scaratec/trellio-mcp\" -n gupta/trellio-mcp\n```\n\nAlso update the pinned version in `smithery.yaml` `commandFunction`.\n\n**The resulting listing stays empty.** Smithery populates an external\nentry by scanning the server over HTTP; this server is stdio-only\n(ADR 002), so the scan fails and the entry carries no connection or\ntool list — even though the publish command reports success. See\n[LIM 0001](docs/limitations/0001-smithery-listing-cannot-be-populated.md).\nInstall via pipx or uvx instead.\n\n### MCP registry\n\n`server.json` describes the server for the official MCP registry by\nstatic declaration rather than introspection. Keep its two `version`\nfields in step with `pyproject.toml`.\n\n## License\n\nThis project is licensed under the GNU General Public License\nv3.0 — see the [LICENSE](LICENSE) file for details.\n",
  "bytes": 9107,
  "sha": "6b59fe9dccbe56961626bafa2a16fcbdb2935d5a572c56eb9f63011193b6af23",
  "repo_slug": "scaratec/trellio-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_scaratec_trellio_mcp_c12360dd/readme"
}