Trello MCP

Claude（Desktop/Cowork および Claude Code）をTrelloボードに接続します。

ボードは設定の board_id で選択されます。特定のボードに関するハードコードは一切ありません。

~/mcp-servers/trello-mcp/
    trello_mcp.py     the server — no credentials inside, safe to share
    requirements.txt  mcp==1.27.2 (pinned, see below)
    .venv/            dedicated Python 3.12 environment
~/.config/trello-mcp/config.json   credentials (chmod 600, never shared)

両方に登録されています：

• ~/Library/Application Support/Claude/claude_desktop_config.json（Desktop/Cowork）

• ~/.claude.json（Claude Code）

どちらも絶対パスのvenvインタプリタを指しています。これは重要です。以下を参照。

毎朝切断された理由

以前の設定では、サーバーを起動するコマンドとして python3 という裸のコマンドを使用していました。このMacには4つの python3 バイナリがあり、mcp パッケージを持っているのは1つだけです：

python3 がどれを指すかは、アプリを起動したプロセスの PATH に依存します。Finder またはログイン時に起動された場合、アプリは最小限の launchd PATH（/usr/bin:/bin:/usr/sbin:/sbin）を継承し、Python 3.9 を取得 → ModuleNotFoundError: No module named 'mcp' → 「Trello MCP に接続できませんでした。」 となります。ターミナルから起動された場合、Anaconda が最初に来るシェルの PATH を継承 → 動作します。つまり、ほとんどの朝は壊れ、手動でテストすると正常に動作する、という状態でした。

以前の失敗と修正を再現：

env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin python3 "$HOME/Claude/Projects/Daily Trello/trello_mcp.py"   # ModuleNotFoundError
env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin ~/mcp-servers/trello-mcp/.venv/bin/python3 -c "import mcp; print('ok')"  # ok

インタプリタを絶対パスで指定することで、PATH の検索はまったく行われなくなります。アプリは既知の1つのバイナリを起動し、そのバイナリは既知の1つのパッケージディレクトリを見つけます。午前7時でも午後7時でも同じ結果です。

Related MCP server: trello-mcp-server

venv の実際の機能（そして防御できないもの）

Python は、実行中の特定のインタプリタに結びついたディレクトリ内のインストール済みパッケージを探します。4つのインタプリタ = 4つの独立したパッケージディレクトリ。mcp はそのうちの1つにしかインストールされていませんでした。venv は、このサーバーだけに属するプライベートなディレクトリを作成します。

技術的には：python3 -m venv .venv は .venv/bin/python3 と、ベースインストールを記録した pyvenv.cfg を作成します。起動時にインタプリタはこのファイルを読み取り、sys.prefix を venv に設定するため、import は .venv/lib/python3.12/site-packages を解決します。

正直な限界： macOS では、venv はインタプリタをコピーするのではなくシンボリックリンクします。標準ライブラリはまだベースインストールからロードされます：

.venv/bin/python3 -> /opt/anaconda3/bin/python3
stdlib             = /opt/anaconda3/lib/python3.12

したがって、この venv は依然として Anaconda がインストールされていることに依存しています。隔離するのはパッケージであり、インタプリタではありません。

これらのいずれかの後に再構築、約15秒：

cd ~/mcp-servers/trello-mcp && rm -rf .venv
/path/to/any/python3.10+ -m venv .venv && ./.venv/bin/pip install -r requirements.txt

もし Anaconda から真に独立したい場合は、uv をインストールし、uv 管理のスタンドアロン Python から venv を構築してください。ここでは、新しいツールをマシンに追加することになるため、行っていません。

mcp を無闇にアップグレードしないでください

requirements.txt は mcp==1.27.2 に固定されています。これは意図的です：mcp 2.0.0 では、このサーバーが構築されている @app.list_tools() / @app.call_tool() デコレータ API が削除されました。最新版をインストールすると、サーバーは即座に AttributeError: 'Server' object has no attribute 'list_tools' で壊れます。これは、この設定全体が修正しようとしていた接続障害とまったく同じように見えます。新しい API 用にハンドラを書き換えると同時にのみアップグレードしてください。

認証情報ファイルの仕組み

~/.config/trello-mcp/config.json：

{ "api_key": "...", "token": "...", "board_id": "676f0bfc11723d27f716291d" }

ホストはなく、外部サービスもありません。このディスク上の通常のJSONファイルです。2つの点で「秘密」になります：

1. コードの外部にあるため、trello_mcp.py をコピーまたは公開しても認証情報は含まれません。

2. chmod 600 — このmacOSユーザーアカウントのみが読み取り可能です。

サーバーは起動時にこれを読み取り、値をメモリに保持します。サーバーを共有するには、trello_mcp.py を送信してください。受信者は自分のTrelloキーで独自の設定を作成します。暗号化ではありません。共有するものと共有しないものを分離することです。

Trelloトークンには有効期限がなく（dateExpires: null）、スコープはメンバー/ボード/組織の読み取り+書き込みです。Google DriveサーバーのOAuthリフレッシュトークンとは異なり、定期的な再認証は必要ありません。

リストは決してハードコードされていません

すべてのリストは、実行時にライブAPIに対して名前で解決されるため、Trelloに追加されたリスト（四半期ごとの新しいクラス）は、コード変更や再起動なしで即座に動作します。60秒のキャッシュによりこれを低コストに保ちます。キャッシュミスが発生すると、「見つかりません」と報告する前に1回の再取得が強制されるため、数秒前に作成されたリストでも解決されます。

このボードで測定：リストの取得には約307ミリ秒かかります。キャッシュがない場合、すべてのツール呼び出しでこれが発生し（get_cards は2往復かかります）、12枚のカードの計画セッションでは再取得だけで約3.7秒を消費します。キャッシュがあれば、1回の取得でバーストをカバーします。

コード内の唯一のリスト名は、trello_mcp.py の先頭にある3つのワークフローアンカーです：

LIST_TODO    = "To Do Today"
LIST_WORKING = "Working on"
LIST_DONE    = "Done Today"

これらは名前付きです。なぜなら、日々のルーチンがこれらを使って定義されているからです（sort_todo_today は名前なしでは「今日を意味するリストを並べ替える」と言えません）。Trelloで名前を変更したら、そのブロックとDaily Trelloの CLAUDE.md で変更してください。rename_list はアンカーを名前変更したときに警告します。

ツール（37個）

読み取り — get_all_lists、get_cards（添付ファイル、ラベル、期限、位置を含む）、get_card（詳細）、search_cards、get_board_summary

カード — create_card（添付ファイル/ラベル/位置指定可能）、update_card、move_card、complete_card、archive_card、unarchive_card、copy_card、set_card_position、set_card_cover、sort_todo_today

添付ファイル — get_attachments、add_attachment（URL または ローカルファイルのアップロード）、view_attachment（画像を表示可能 — これによりClaudeはカード上のスクリーンショットを読み取ります）、delete_attachment

ラベル — get_labels、add_label_to_card、remove_label_from_card、create_label

コメント — get_comments、add_comment

リスト — create_list、rename_list、archive_list、move_list

チェックリスト — get_checklists、create_checklist、add_checklist_item、complete_checklist_item、uncheck_checklist_item、rename_checklist_item、delete_checklist_item、delete_checklist

既知のボード設定：コメントが無効

add_comment は、ボード自体でコメントがオフになっているため（prefs.comments: "disabled"）401を返します。トークンやコードの問題ではありません。有効にするには：Trello → ボードメニュー（···）→ 設定 → コメント権限 → ボードメンバー。ツールはこれを検出し、生の401を表示する代わりに説明します。

search_cards に関する注意

Trelloの検索インデックスは数秒遅れます。作成されたばかりのカードはまだ表示されない場合があります。その場合は、代わりにそのリストの get_cards を使用してください。

トラブルシューティング

# 1. Does the interpreter still work?
~/mcp-servers/trello-mcp/.venv/bin/python3 -c "import mcp; print('ok')"

# 2. Does the server start and reach Trello? (Ctrl-C to exit; silence = healthy)
~/mcp-servers/trello-mcp/.venv/bin/python3 ~/mcp-servers/trello-mcp/trello_mcp.py

# 3. Are the configs still pointing at the venv?
grep -A3 '"trello"' ~/.claude.json "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

いずれかの設定を変更した後は、アプリを完全に終了して再度開いてください。MCPサーバーは起動時にのみ起動されます。

このスクリプトの古いコピーはまだ ~/Claude/Projects/Daily Trello/trello_mcp.py と ~/Downloads/trello_mcp.py にあります。それらを指しているものは何もありません。それらにはまだ埋め込まれた認証情報が含まれているため、その2つは共有しないでください。

履歴書/ポートフォリオ用

将来の履歴書セッションで、再構築ではなく正直なバージョンが得られるようにここに残します。

語る価値のあるストーリーは、機能ではなく障害です。このサーバーは、何週間も毎朝失敗し、手動でテストするたびに動作しました。これがまさに診断です：コードは問題なく、環境が問題でした。設定は python3 と指定していました。ログイン時に起動されたアプリは最小限の PATH（/usr/bin:/bin:/usr/sbin:/sbin）を継承し、そこで解決されるのは必要なパッケージがまったくないシステムPythonです。一方、ターミナルは正しく解決される PATH を継承します。シェルからテストすることは、合格することが保証されている唯一のケースでした。

私が実際に行ったこと： デバッグを指揮しました。私が決断を下しました。「テストしたときに動く」をコードの安心材料ではなく、テストに関する証拠として扱い、便利な条件ではなく、実際の起動条件（PATH を削除した状態）を再現するテストを要求しました。

その結果生まれたもの、現在はすべての統合に適用されています：設定での絶対パスのインタプリタ、プロジェクトごとの専用環境、すべての依存関係の固定、そして既知の各障害モードをチェックし、可能なものを修復するドクタースクリプト。

ポートフォリオ用の箇条書き：

macOSとクラウドサービスを接続する3つの自動化統合の開発を指揮し、スケジュールジョブで無人実行。定期的な毎日の障害を、シェルとアプリ起動コンテキストのPATH解決の違いに原因を特定し、絶対パスと固定依存関係の規則を確立して、3つすべてでそれを排除しました。

完全なケーススタディ：https://zeno-blade-creator.github.io/projects/personal-integrations.html