Trello

trellio-mcp — Trello 用 MCP サーバー

Claude Desktop、Claude Code、Gemini CLI から Trello API に完全にアクセスできる MCP サーバーです。 trellio の非同期クライアントライブラリと、公式 Python MCP SDK を基盤に構築されています。 BDD Guidelines v1.8.0 に従って開発されています。

機能

• 48 個の MCP ツール — trellio のメソッドに 1 対 1 で対応し、複合的な get_board_overview ツールを 1 つ追加
• 2 つのリソーステンプレート — 詳細なコンテキストを読み込むための trello://board/{id} と trello://card/{id}
• 3 つのプロンプト — ワークフローを効率化する summarize_board、create_sprint、daily_standup
• 組み込みの認証フロー — python -m trello_mcp auth を実行するとブラウザーが開き、ユーザーが「Allow」をクリックすると、トークンが安全に保存されます
• 構造化されたエラー処理 — Trello API のエラーを、明確で対処可能な MCP エラーメッセージに変換します
• stdio トランスポート — ローカルのサブプロセスとして実行され、ネットワークに公開されません

ツール

カテゴリー	ツール	数
検索	list_boards, search	2
ボード	get_board_overview, create_board, get_board, update_board, delete_board	5
リスト	list_lists, create_list, update_list, archive_list	4
カード	list_cards, create_card, get_card, update_card, archive_card, unarchive_card, delete_card, add_label_to_card, remove_label_from_card	9
ラベル	list_board_labels, create_label, update_label, delete_label	4
チェックリスト	list_card_checklists, create_checklist, delete_checklist, create_check_item, update_check_item, delete_check_item	6
コメント	list_comments, add_comment, update_comment, delete_comment	4
メンバー	get_me, list_board_members, get_member	3
添付ファイル	list_attachments, create_attachment, get_attachment, upload_attachment, download_attachment, delete_attachment	6
Webhook	list_webhooks, create_webhook, get_webhook, update_webhook, delete_webhook	5

カードツールでは、作成時と更新時に pos（上部／下部）、idLabels（カンマ区切り）、due（ISO 8601）、dueComplete（true／false）を指定できます。

前提条件

• Python 3.10+
• Trello API Key（Allowed Origins に http://localhost:8095 を追加してください）

インストール

pipx を使用する（推奨）

trellio-mcp コマンドを PATH から利用できるよう、グローバルにインストールします。

pipx install trellio-mcp

または、インストールせずに一時的に実行することもできます。

pipx run trellio-mcp

(注：pipx run を使用する場合、MCP クライアントの設定でもコマンドに pipx を、引数に run trellio-mcp を指定する必要があります。)

pip を使用する

pip install trellio-mcp

ソースからインストールする

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

認証

対話形式（推奨）

各マシンで認証コマンドを実行し、Trello アカウントに接続します。

グローバルにインストールした場合（pipx install または pip install）：

TRELLO_API_KEY=your_api_key trellio-mcp auth

一時的な実行（pipx run）を使用する場合：

TRELLO_API_KEY=your_api_key pipx run trellio-mcp auth

ブラウザーが開き、アプリを認証できます。トークンは自動的に取得され、~/.config/trellio-mcp/credentials.json に保存されます（権限 0600）。

認証後は環境変数は不要です。サーバーは起動時に保存された認証情報を読み込みます。

環境変数（代替手段）

保存された認証情報が見つからない場合、サーバーは環境変数にフォールバックします。

export TRELLO_API_KEY=your_api_key
export TRELLO_TOKEN=your_token

MCP クライアントの設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

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

保存された認証情報の代わりに環境変数による認証を使用する場合は、次を追加します。

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

Claude Code

~/.claude/settings.json またはプロジェクトの .claude/settings.json に追加します：

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

Gemini CLI

~/.gemini/settings.json に追加します：

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

アーキテクチャ

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

主な決定事項（docs/adr/ に記載）：

ADR	決定事項
001	trellio との言語の整合性を考慮し、Python MCP SDK を採用
002	stdio トランスポートを採用 — ネットワーク攻撃対象領域なし
003	保存済み認証情報を使用し、環境変数をフォールバックとして利用
004	1:1 のツールマッピング — trellio の各メソッドに対して 1 つのツールを用意
005	trellio を PyPI の依存関係として採用（>=1.4.0）
006	MCP の機能としてツール、リソース、プロンプトを提供
007	isError=true と構造化されたエラー内容を使用

受け入れた弱点は、別途 docs/limitations/ に記録されています。ここに記載された制限事項は、すでに適切な解決策と比較検討したうえで、対応しないと判断したものです。既知の不完全な動作に対する修正を提案する前に、一覧を確認してください。

テスト

このプロジェクトでは、BDD ガイドライン v1.8.0に従い、 behave を使用した BDD を採用しています。

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 の実行にはネットワークアクセスが必要です。このテストは wheel をビルドし、宣言された mcp のバージョン範囲の両端にある一時的な環境へインストールして、生成されたサーバーを stdio 経由で操作します。壊れた依存関係の宣言を検出できるのはこのテストだけです。他のテストはローカルの .venv に対してツール関数をインポートします。依存関係のガードは実行を要求しなければ機能しない、ということがないよう、意図的にオプトインタグを付けていません。オフラインでテストスイートを実行するには、明示的に除外してください：

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

テストのアーキテクチャ：

• AsyncMock(spec=TrellioClient) — HTTP ではなく、クライアント境界でモックを使用
• モックの呼び出し記録による永続化の検証（§4.3）
• 2 つ以上のバリエーションを持つシナリオアウトラインによるハードコーディングの防止（§2.3）
• 各レイヤーの障害経路を網羅（§4.5）
• §13 に従った独立した仕様監査

BDD による開発プロセスの詳細については、ケーススタディを参照してください。

プロジェクト構成

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

公開

PyPI

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

Smithery

名前空間は gupta です。新しい PyPI バージョンを公開した後、リリースを更新してください：

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

smithery.yaml の commandFunction に記載された固定バージョンも更新してください。

公開後の一覧は空のままです。 Smithery はサーバーを HTTP 経由でスキャンして外部エントリーを登録します。このサーバーは stdio 専用（ADR 002）のため、スキャンに失敗し、公開コマンドが成功を報告しても、エントリーには接続情報もツール一覧も登録されません。LIM 0001を参照してください。代わりに pipx または uvx でインストールしてください。

MCP レジストリ

server.json は、イントロスペクションではなく静的な宣言によって、公式 MCP レジストリ向けにサーバーを記述します。2 つの version フィールドを pyproject.toml と一致させてください。

ライセンス

このプロジェクトは GNU General Public License v3.0 のもとでライセンスされています。詳細については LICENSE ファイルを参照してください。