trello-mcp

trello-mcp

MCP 対応クライアントから Trello のカード、リスト、ラベル、添付ファイル、チェックリスト、メンバー、カードのアクティビティを操作できる、セルフホスト可能な Model Context Protocol サーバーです。

このプロジェクトは、意図的にセルフホスト可能で再利用しやすい設計になっています。貢献、応用、対象を絞った課題報告を歓迎します。

もちろん、ロードマップは Trello で管理されており、trello-mcp が最新の状態に保つのに役立ちます：trello-mcp のロードマップ。

免責事項

trello-mcp は、独立したコミュニティ運営のプロジェクトです。公式の Trello または Atlassian の製品、サービス、MCP 実装ではなく、Trello または Atlassian との提携、承認、後援も受けていません。

このプロジェクトは、MCP 対応の LLM クライアントが、Trello の公開 APIとユーザー提供の API 認証情報を通じて、Trello と連携しやすくすることを目的としています。

Trello の公式ホスト型 MCP サーバーをお探しですか？Trello MCP にアクセスし、Trello がドキュメントに記載しているエンドポイント https://mcp.trello.com/v1 をご利用ください。

ドキュメント

プロジェクトのドキュメント一式は trello-mcp.com でご覧いただけます。

• はじめに
• Trello API キーとトークンの作成
• MCP クライアントのセットアップ
• ツールカタログを見る
• API の対応範囲と対象外の機能を確認する
• セキュリティとデータについて
• 稼働中のデプロイメントを運用する
• インストールのトラブルシューティング
• 公式 MCP Registry のインストール、リリース、復旧
• Glama の掲載ページ（検証状況）

機能

ボードの検出

• 認証済みの Trello メンバーに表示されるボードを一覧表示します。
• ボードの基本的なメタデータを読み取ります。
• ボード上の未完了、完了、またはすべてのリストを一覧表示します。
• ボード上の未完了、完了、表示中、またはすべてのカードを一覧表示します。
• ボードのラベル、メンバー、メンバーシップを一覧表示します。
• ボードのラベルを作成、確認、更新、削除します。
• リストを作成、確認、名前変更、アーカイブ、アーカイブ解除し、ボード間で移動します。

カードのワークフロー

• ID、短縮 ID、または Trello カード URL でカードを読み取ります。
• タイトル、説明、期限、位置、メンバー、ラベルを指定してカードを作成します。
• タイトル、説明、期限、期限の完了状態、アーカイブ状態など、カードのメタデータを更新します。
• カードをリスト間またはボード間で移動します。
• 既存のラベルをカードに適用、またはカードから削除します。
• 明示的に要求された場合にのみ、カードを完全に削除します。

カードのコンテキスト

• Trello リスト内のカードを一覧表示します。
• カードの添付ファイルを一覧表示、個別に確認し、公開 URL の添付ファイルを追加します。また、明示的に設定したディレクトリからサーバー上のファイルをアップロードします。
• カードのチェックリストを一覧表示、作成、名前変更、削除し、チェックリストの項目を管理します。
• カードのメンバーを一覧表示し、メンバーを追加または削除します。
• カードのアクションとアクティビティ履歴を読み取ります。
• Trello カードのコメントを追加、編集、削除します。

検索ワークフロー

• Trello の検索テキストと演算子を使って、Trello のカード、ボード、メンバー、ワークスペースを検索します。
• 検索結果を特定のボード、カード、またはワークスペースに絞り込みます。
• 割り当てる前に、名前またはユーザー名で Trello メンバーを検索します。
• メンバーのプロフィール、割り当てられたカード、ボード、ワークスペースを読み取ります。

ワークスペースの検出

• 認証済みのメンバーに表示される Trello ワークスペースを一覧表示します。
• ワークスペースのメタデータ、ボード、メンバーを読み取ります。

セルフホスト可能なランタイム

• 公開されている GHCR イメージを使用して Docker Compose で実行します。
• 別の Compose ファイルを使用してローカルでビルドします。
• コンテナーのデプロイには Streamable HTTP を使用します。
• サーバーを子プロセスとして起動するローカル MCP クライアントには stdio を使用します。
• ローカル MCP クライアントがプロトコル専用の stdout を受け取れるよう、stdio のログは stderr に出力します。
• HTTP のヘルスチェックおよびレディネスのエンドポイントを公開します。
• HTTP MCP エンドポイントへのリクエストにベアラートークンを任意で要求します。
• Zod を使用して設定、ツール入力、Trello API のレスポンスを検証します。
• ログから Trello の認証情報をマスキングします。
• GitHub Actions で型チェック、Lint、ビルド、テスト、カバレッジを実行します。

クイックスタート

1. Trello API の認証情報を取得する

Trello API キーは、Trello のアプリ管理ポータルにあるアプリから作成します。このサーバーを実行する各ユーザーは、自分の Trello アカウントとトークンを使用してください。最新のセキュリティを重視した手順については、専用の Trello API 認証情報ガイドを参照してください。

簡単に説明すると、trello.com/apps/admin でアプリを作成または選択し、その API Key タブからキーを生成します。次に、近くにある Token リンクを使用して、対象の Trello メンバーへのアクセスを確認し、認可します。

これらの値を次のように使用します。

TRELLO_API_KEY=your-api-key
TRELLO_TOKEN=your-token

2. インストール方法を選ぶ

オプション A：公開済みの Docker イメージを実行する

サーバーを実行するだけの場合は、この方法を使用してください。GHCR からビルド済みのイメージを取得するため、ローカルでビルドする必要はありません。

git clone https://github.com/enthouan/trello-mcp.git
cd trello-mcp
cp .env.example .env

.env を編集し、プレースホルダーの値を置き換えます。

TRELLO_API_KEY=your-api-key
TRELLO_TOKEN=your-token
TRANSPORT=http
LOG_LEVEL=info
TRELLO_RATE_LIMIT_CAPACITY=100
TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS=10000
TRELLO_RETRY_MAX_ATTEMPTS=3
TRELLO_RETRY_BASE_DELAY_MS=100
TRELLO_RETRY_MAX_DELAY_MS=2000
# MCP_AUTH_TOKEN=optional-shared-secret
TRELLO_MCP_HOST_BIND_IP=127.0.0.1
TRELLO_MCP_HOST_PORT=3000
TRELLO_MCP_IMAGE_TAG=latest
TRELLO_MCP_NETWORK=trello-mcp_network

公開済みのイメージを起動します。

docker compose up -d --wait --wait-timeout 120

デフォルトの docker-compose.yml では、次の値が使用されます。

ghcr.io/enthouan/trello-mcp:latest

イメージタグ、ホストのバインド IP、ホストポート、ネットワーク名などの Docker Compose の値は、環境変数または .env ファイルで上書きできます。Compose ファイルの先頭にはデフォルト値が記載されています。たとえば、docker-compose.yml では TRELLO_MCP_IMAGE_TAG のデフォルトは latest タグです（latest は main ブランチに追従し、バージョンを指定したデプロイには X.Y や X.Y.Z などのリリースタグを使用できます）。TRELLO_MCP_HOST_BIND_IP のデフォルトはローカルからのみアクセスできる 127.0.0.1、TRELLO_MCP_HOST_PORT のデフォルトは 3000 で、このホストポートをコンテナ内の固定ポート 3000 にマッピングします。また、TRELLO_MCP_NETWORK のデフォルトは trello-mcp_network です。LAN アクセスなど、Docker がサービスをすべてのホストインターフェースで公開する必要がある場合に限り、TRELLO_MCP_HOST_BIND_IP=0.0.0.0 を設定してください。

HTTP MCP リクエストで /mcp に対する Authorization: Bearer <token> を必須にするには、MCP_AUTH_TOKEN を設定します。デフォルトの認証なしのローカル動作にする場合は、設定しないでください。ヘルスチェック用およびレディネスチェック用のエンドポイントは、コンテナやリバースプロキシからのチェックに備えて、引き続き認証なしで利用できます。

コンテナのヘルスチェックは TRANSPORT に従います。HTTP の場合は PORT（デフォルトは 3000）の /healthz をチェックし、stdio の場合はプロセスの稼働状況を確認し、接続された MCP クライアントがプロトコルの応答性をチェックします。Compose では、このイメージのヘルスチェックが引き継がれます。

大規模なワークフロー中にログで trello rate limit wait または trello request rate limited; retrying が確認されない限り、Trello のレート制限と再試行の値はデフォルトのままにしてください。トークンを共有する場合や、デプロイ環境に制約がある場合は容量を下げてください。ワークフローのボード、カード、フィールド、ページネーションの対象範囲を絞り込んだ後でのみ、慎重に容量を上げてください。

再現可能なデプロイを行うには、リリースを選択し、検証済みのインデックスダイジェストを固定してください。 SBOM／来歴情報の検査、GHCR の署名ポリシー、Docker ビルドによる別のカタログ経路については、イメージの信頼性と読み取り専用の検証を参照してください。 メタデータの整合性チェックによって、発行者が認証されるわけではありません。公開済みの Docker イメージタグには、次の規則が適用されます。

タグ	用途
latest	現在の main ブランチのビルドに追従します。最新の main ブランチのイメージを意図的に使う場合に使用します。
X.Y	マイナーバージョン系列の最新パッチリリースに追従し、一致する最新の vX.Y.Z タグからビルドされたイメージに移動します。
X.Y.Z	正確なリリースを識別し、プロジェクトのポリシーに従って保持されます。バイト列を不変にするには、検証済みのダイジェストを固定してください。
sha-<commit>	コミットのビルドを識別します。安定版リリースによって、このエイリアスを検証済みリリースのダイジェストに修正できます。

Compose を使わずに、公開済みのイメージを直接実行することもできます。

docker run --rm -p 127.0.0.1:3000:3000 \
  -e TRELLO_API_KEY=your-api-key \
  -e TRELLO_TOKEN=your-token \
  ghcr.io/enthouan/trello-mcp:latest

オプション B：ソースからローカルでビルドする

プロジェクトの開発、ローカルの変更のテスト、または Docker イメージの独自ビルドを行う場合は、この方法を使用してください。

ローカル開発では、Node.js 24.x と、Corepack を介して固定された [email protected] パッケージマネージャーを使用します。

git clone https://github.com/enthouan/trello-mcp.git
cd trello-mcp
cp .env.example .env

.env に Trello の認証情報を設定し、ローカルでビルドして実行します。

docker compose -f docker-compose.local.yml up --build -d --wait --wait-timeout 120

これにより、ローカルの Dockerfile からビルドし、イメージに trello-mcp:local というタグを付ける docker-compose.local.yml が使用されます。

Docker を使用しないローカルビルドの場合：

corepack enable
corepack prepare [email protected] --activate
corepack pnpm install --frozen-lockfile
corepack pnpm build:clean

次に、コンパイル済みのサーバーを直接実行します。

TRELLO_API_KEY=your-api-key TRELLO_TOKEN=your-token TRANSPORT=stdio node dist/index.js

トークンはパスワードと同様に扱ってください。コミットしたり、ログに貼り付けたり、PR で共有したりしないでください。

3. MCP クライアントを接続する

サーバーの実行場所に応じて、トランスポートを選択してください。

環境	選択肢	クライアントが受け取る情報
ビルド済みのクローンと MCP クライアントが同じマシンにある	stdio	ローカルコマンドと、子プロセスの環境変数に設定する Trello 認証情報
サーバーが Docker 内、リバースプロキシの背後、または別のホストで実行されている	ストリーミング可能な HTTP	/mcp URL と任意のベアラートークン。Trello 認証情報はサーバー上に保持されます

Set up your MCP client guideには、Claude Desktop、Claude Code、Codex CLI、VS Code、OpenCode、MCP Inspector、その他の手動で設定するクライアント向けの、最新かつ機密情報を除いた例があります。また、再起動の要件、HTTP ベアラー認証への対応、シークレットの取り扱い、テスト済みの制限事項についても説明しています。

クライアントのバージョンとその根拠については、MCP Client Compatibilityを参照してください。

4. 確認する

ストリーミング可能な HTTP を選択した場合は、サーバーを確認します。

curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz

TRELLO_MCP_HOST_PORTを変更した場合は、3000をそのホストポートに置き換えてください。TRELLO_MCP_HOST_BIND_IPを127.0.0.1から変更した場合は、バインドされたホストインターフェースにアクセスできるホスト名または IP アドレスを使用してください。

続いて、MCP クライアントが現在の 77 個のツールを検出することを確認します。読み取り専用の認証情報確認として、クライアントからauth_whoamiまたはauth_token_infoを呼び出してください。セットアップを確認するだけの目的で、Trello への書き込み呼び出しは行わないでください。

Trello 認証情報

このサーバーでは現在、Trello API キーとトークンによる認証を使用しています。セキュリティに重点を置いた手順については、専用のTrello API credentials guideを参照してください。Trello の公式 App Admin Portal、認証、取り消しに関するドキュメントへのリンクも掲載されています。

読み取り専用のauth_whoamiツールとauth_token_infoツールを使って、設定済みの認証情報でどの Trello メンバーとして認証されるかを確認し、設定済みトークンの所有者、有効期限、権限を調べることができます。これらのツールは診断専用です。このサーバーは、OAuth リダイレクト、トークンの作成、トークンの更新、トークンの取り消し、その他のトークンライフサイクル管理には対応していません。

MCP クライアントをセットアップする

トランスポートの選択とクライアント固有の設定については、標準のSet up your MCP client guideを参照してください。Trello 認証情報はstdioの子プロセス環境か HTTP サーバー上に保持してください。HTTP クライアントに必要なのは、/mcpエンドポイントと、MCP_AUTH_TOKENが有効な場合に、対応するベアラーヘッダー設定だけです。

互換性記録では、公式ドキュメントの確認と、実際のクライアント接続、ツールの検出、実際の Trello ワークフローを区別しています。

環境

デプロイ環境ごとの適用条件、シークレットの取り扱い、レート制限の調整、Compose の制御、ローカルの添付ファイルアップロード要件については、設定リファレンスを参照してください。

変数	必須	デフォルト	説明
TRELLO_API_KEY	はい		Trello API キー。
TRELLO_TOKEN	はい		トークン認証用の Trello トークン。
MCP_AUTH_TOKEN	いいえ		設定すると、/mcp への HTTP MCP リクエストには Authorization: Bearer <token> が必要です。HTTP ベアラートークンのチェックを行わない場合は、未設定のままにします。
TRELLO_ATTACHMENT_UPLOAD_ROOT	いいえ		ローカルファイルの添付ファイルアップロードを有効にする、サーバー側の絶対パスのディレクトリです。ローカルアップロードを無効にする場合は、未設定のままにします。
TRELLO_RATE_LIMIT_CAPACITY	いいえ	100	クライアントがトークンの補充を待つまでの、Trello リクエスト用トークンバケット容量です。正の整数を指定してください。
TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS	いいえ	10000	トークンバケットの補充間隔（ミリ秒）です。正の整数を指定してください。
TRELLO_RETRY_MAX_ATTEMPTS	いいえ	3	Trello が HTTP 429 を返した場合の、Trello リクエストの総試行回数です。正の整数を指定してください。
TRELLO_RETRY_BASE_DELAY_MS	いいえ	100	HTTP 429 の再試行における指数バックオフの基本待機時間（ミリ秒）です。上限付きのジッターが適用されます。正の整数を指定してください。
TRELLO_RETRY_MAX_DELAY_MS	いいえ	2000	HTTP 429 の再試行で待機する時間の最大値（ミリ秒）です。正の整数を指定してください。
TRANSPORT	いいえ	http	http または stdio。
PORT	いいえ	3000	Node プロセスの HTTP リッスンポートです。Docker Compose ではコンテナのリッスンポートを 3000 に固定し、公開するホストポートには TRELLO_MCP_HOST_PORT を使用します。
LOG_LEVEL	いいえ	info	Pino のログレベルです。
TRELLO_MCP_HOST_BIND_IP	いいえ	127.0.0.1	Docker Compose のホストインターフェースのバインドアドレスです。ローカルのみのアクセスには 127.0.0.1 のままにします。意図的にネットワーク／LAN に公開する場合は 0.0.0.0 を設定します。
TRELLO_MCP_HOST_PORT	いいえ	3000	コンテナ内部の固定リッスンポート 3000 にマッピングする Docker Compose のホストポートです。
TRELLO_MCP_IMAGE_TAG	いいえ	latest	公開イメージのタグです。latest は main を追跡し、X.Y はそのマイナーリリース系列の最新パッチを追跡し、X.Y.Z は特定のリリースに固定されます。
TRELLO_MCP_NETWORK	いいえ	trello-mcp_network	Docker Compose のブリッジネットワーク名です。

Trello ライブスモークテスト

通常のテストはモックを使用し、オフラインで実行されます。corepack pnpm test、corepack pnpm test:coverage、およびデフォルトの CI ワークフローでは、Trello の認証情報は不要で、Trello への接続も行いません。

実際の Trello を使ってリリース検証を行う場合は、明示的なライブスモークコマンドを使用します。

TRELLO_LIVE_SMOKE=1 \
TRELLO_LIVE_SMOKE_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm smoke:live

TRELLO_LIVE_SMOKE_BOARD_ID の代わりに TRELLO_LIVE_SMOKE_BOARD_URL を使用できます。Trello の trello.com/b/... ボード URL は短縮リンクに正規化され、その後、ハーネスは何かを作成する前に board_get で正規のボード ID を解決します。ボード URL 以外は、生の値やクエリ文字列をログに記録せずに拒否されます。TRELLO_LIVE_SMOKE_RUN_ID は任意で、設定すると一時的なアーティファクト名に含まれます。

出力を公開する可能性がある場合は、TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1 を設定してください。その場合、ハーネスはボードの ID を記録したり書き込みを行ったりする前に、Trello からボードが公開状態と報告されていることを確認します。ローカルで非公開の使い捨てボードを使って検証する場合は、この設定は任意です。

安全性に関するモデル：

• TRELLO_LIVE_SMOKE=1、Trello の認証情報、およびスモークテスト用のボード ID または URL がすべてそろっていない限り、Trello へのリクエストを行う前にコマンドは終了します。
• 設定するボードには、本番環境で使用中のボードではなく、検証用に確保した使い捨てボードを使用してください。
• ハーネスは、一意の名前を付けた一時リスト、カード 1 枚、ラベル 1 個、チェックリスト 1 個、チェックリスト項目 1 個、コメント 1 件を作成します。カードとラベルを削除し、一時リストをアーカイブして、未完了の一時リスト、カード、ラベルが残っていないことを確認します。
• 中間の検証手順が失敗した場合でもクリーンアップを実行します。また、Trello が作成したものの、レスポンス検証エラーが追跡可能になる前に作成された一意のプレフィックス付きリスト、カード、ラベルも検索します。クリーンアップに失敗した場合はその旨を報告し、コマンドを失敗させます。
• ハーネスは、実際の TrelloClient を使って既存のツールハンドラーを呼び出すため、ツール入力の検証、Trello レスポンスの検証、再試行とレート制限の処理、認証情報の秘匿化は、通常のコードパスで行われます。
• ハーネスは、API キー、トークン、認証情報を含む URL、生の環境オブジェクト、生のリクエストデータをログに記録しません。

このスモークテストのフローでは、代表的な v1.0 ワークフローを検証します。

• 認証と探索：auth_whoami、auth_token_info、list_boards、ボードの読み取り、リスト、カード、ラベル、メンバー、メンバーシップ、カスタムフィールドの探索。
• リストとカードの書き込み：使い捨てリストの作成／名前変更／アーカイブ、カードの作成／読み取り／更新／期限設定／位置変更／アーカイブ／復元／移動／削除。
• チェックリストと項目の動作：チェックリストの作成／名前変更／削除、および項目の作成／一覧取得／更新／チェック／削除。
• ラベルとメンバー：使い捨てラベルの作成／読み取り／更新／適用／解除／削除、およびスモークテスト用ボードで表示される場合の、認証済みメンバーの割り当て／解除。
• カードのアクティビティ：使い捨てカード上でのコメントの作成／更新／一覧取得／削除。

Trello ライブ回帰テスト

corepack pnpm smoke:live は、リリース向けの簡易スモークチェックです。最も重要なワークフローで認証し、使い捨てのアーティファクトを作成して変更し、クリーンアップできることを確認します。corepack pnpm regression:live は、より広範な、明示的なオプトイン方式のリリース検証スイートです。ドメインごとに MCP の公開ツール群を検証し、登録済みツールカタログに対するライブカバレッジを報告するとともに、未実行または不足しているライブカバレッジを可視化します。

回帰テストスイートには、スモークテストとは別のオプトイン用ゲートがあります。

TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live

trello.com/b/... のボード URL のほうが便利な場合は、TRELLO_LIVE_REGRESSION_BOARD_ID の代わりに TRELLO_LIVE_REGRESSION_BOARD_URL を使用してください。ボード URL 以外は、Trello へのリクエストを行う前に、生のクエリ文字列をログに記録せずに拒否されます。

出力または JSON レポートを公開する可能性がある場合は、TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1 を設定してください。その場合、ハーネスはボードの ID を記録したり書き込みを行ったりする前に、設定されたすべてのボードが Trello から公開状態と報告されていることを確認します。ローカルで非公開の使い捨てボードを使って実行する場合は、このフラグを省略し、出力を非公開にできます。 クロスボード間でリストを移動するライブカバレッジが必要な場合は、TRELLO_LIVE_REGRESSION_SECONDARY_BOARD_ID または TRELLO_LIVE_REGRESSION_SECONDARY_BOARD_URL を設定してください。セカンダリボードはローカル実行では任意です。設定されていない場合、カバレッジ不足ではなく、list_move_to_board は意図的な実行時スキップとして報告されます。設定されている場合、スイートは board_get でボードを解決し、list_boards を通じてトークンから参照できることを確認し、ボードがオープン状態でプライマリボードとは異なることを検証してから、破棄可能なリストのみを2つのボード間で移動します。

ドメインまたは1つのツールをデバッグする場合は、対象を絞った実行が便利です。

TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live --domain cards

TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live --tool card_attachment_upload

TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-primary-disposable-board-id-or-short-link \
TRELLO_LIVE_REGRESSION_SECONDARY_BOARD_ID=your-secondary-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live --tool list_move_to_board

TRELLO_LIVE_REGRESSION_DOMAINS=cards,attachments および TRELLO_LIVE_REGRESSION_TOOLS=card_get,card_update も使用できます。サポートされているドメインは、auth、boards、lists、cards、labels、checklists、members、workspaces、search、custom-fields、comments-actions、attachments です。

人間が読めるターミナルレポートに加えて、機械可読なレポートを出力するには、TRELLO_LIVE_REGRESSION_REPORT_JSON=reports/live-regression.json を設定してください。レポートではツールがドメイン別に分類され、次の内容が示されます。

• covered：Trello に対して正常に実行されたツールハンドラー。
• skipped：表示可能なワークスペースがない、ボードにカスタムフィールドがない、アップロードカバレッジが設定されていない、などの意図的な実行時スキップ。
• unsupported：board_create など、回帰テストの対象外として意図的に除外されたライブケース。
• missing：カバレッジの分類がない、選択された公開ツール。新しい公開ツールがリリース検証から暗黙のうちに漏れないよう、カバレッジ不足があるとコマンドは失敗します。
• クリーンアップのステータス。試行済み／完了したクリーンアップ手順と、プレフィックスに一致する未処理のオープン状態のアーティファクトを含みます。

回帰テストの安全性モデル：

• TRELLO_LIVE_REGRESSION=1、Trello の認証情報、回帰テスト用ボード ID または URL のすべてが設定されていない限り、Trello へのリクエストを送信する前にコマンドは終了します。
• 設定するボードには、アクティブな本番ボードではなく、検証用に確保した破棄可能なボードを使用してください。
• 任意のセカンダリボードも破棄可能なものにしてください。このボードが変更されるのは list_move_to_board の実行時のみで、回帰テストの実行によって作成されたリストだけが対象です。
• 一時アーティファクトには一意の実行 ID と trello-mcp live regression ... プレフィックスが使用されます。人間が読める実行マーカーを指定する場合は、TRELLO_LIVE_REGRESSION_RUN_ID を設定してください。
• 中間処理で失敗した場合もクリーンアップが実行されます。追跡対象の一時カード、ラベル、添付ファイル、メンバー／ラベルの割り当て、カスタムフィールドの値を削除し、一時リストをアーカイブします。また、レスポンスを追跡する前に作成された、プレフィックスに一致するリスト、カード、ラベルを、設定済みのすべての回帰テスト用ボードから検索します。
• スイートは実際の TrelloClient を使って登録済みのツールハンドラーを呼び出します。別途用意したアドホックなクライアントを通じて Trello を呼び出すことはありません。
• API キー、トークン、認証情報を含む URL、生の環境オブジェクト、生のリクエストデータはログに記録されません。

ローカルファイルのアップロードカバレッジはデフォルトでスキップされます。card_attachment_upload を含めるには、通常のアップロードルートと、明示的な回帰テストファイルの両方を設定する必要があります。

TRELLO_ATTACHMENT_UPLOAD_ROOT=/absolute/path/to/trello-uploads \
TRELLO_LIVE_REGRESSION_UPLOAD_FILE=sample.txt \
TRELLO_LIVE_REGRESSION=1 \
TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm regression:live --domain attachments

アップロードファイルのパスは TRELLO_ATTACHMENT_UPLOAD_ROOT からの相対パスまたは絶対パスを指定できますが、アップロードルート内に解決される必要があります。

ローカル検証時にライブ環境変数が設定されていない場合は、ライブコマンドをスキップとして記録してください。スキップ状態は明示されます。corepack pnpm smoke:live と corepack pnpm regression:live は、Trello に接続する前に失敗し、不足している変数名を出力します。ジョブがシークレットを使用し、オプトインで実行される場合を除き、通常の CI にどちらのコマンドも追加しないでください。

GitHub Actions

このリポジトリには、PR、マージ後の main、リリースの検証に使用する Live Trello Smoke ワークフローが含まれています。同一リポジトリ内のプルリクエスト、main へのプッシュ、手動実行で動作します。フォークからのプルリクエストはスキップされるため、信頼できないPRコードにTrelloの認証情報が公開されることはありません。

このワークフローは、シークレットを使用するライブスモークテストの前に、オフラインのゲート（pnpm typecheck、pnpm lint、pnpm build、pnpm test）を実行します。

使用する前に、次のシークレットを設定した live-smoke という名前の GitHub Environment を構成してください。

Secret	説明
TRELLO_LIVE_SMOKE_API_KEY	スモークテスト専用のTrelloメンバー用Trello APIキーです。
TRELLO_LIVE_SMOKE_TOKEN	同じメンバー用のTrelloトークンです。使い捨てのスモークテスト用ボードへの書き込みアクセス権が必要です。

リポジトリにメンテナーが複数いる場合、またはトークンがスモークテスト用ボード以外にもアクセスできる場合は、環境の必須レビュアーを設定してください。このワークフローでは、pnpm smoke:live ステップに限り、これらのシークレットを TRELLO_API_KEY と TRELLO_TOKEN に割り当てます。ジョブでは environment.deployment: false を設定しているため、GitHub Environment によるシークレットのスコープ設定と保護ルールは維持されますが、Deployment レコードは作成されません。このワークフローでは pull_request_target を使用しないでください。

ホスト型スモークテストワークフローは、公開されている使い捨てテスト用ボードの短縮リンク hUaItfNq に固定されており、TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1 を設定します。そのため、Trelloでそのボードが公開状態でなくなった場合、IDの出力や書き込みの前に失敗します。ボードの上書きは受け付けないため、メンテナーが誤って非公開ボードの識別子を公開Actionsログやサマリーに掲載することはありません。一時的なアーティファクト名やアクティビティ履歴が見える場合でも、公開ボードはスモークテストに使用できます。ただし、ハーネスは書き込みを行うため、公開ボードであってもTrelloの認証情報が必要です。別の使い捨てボードを使用する場合は、上記のローカルコマンドを使い、非公開ボードの出力を公開ログやアーティファクトに含めないでください。

より広範な Live Trello Regression ワークフローは手動実行のみで、通常のPRゲートではなく、リリース候補や目的を絞ったライブデバッグに使用してください。次の設定で live-regression という名前の GitHub Environment を構成してください。

Secret	説明
TRELLO_LIVE_REGRESSION_API_KEY	回帰テスト専用のTrelloメンバー用Trello APIキーです。
TRELLO_LIVE_REGRESSION_TOKEN	同じメンバー用のTrelloトークンです。使い捨ての回帰テスト用ボードへの書き込みアクセス権が必要です。

ホスト型回帰テストワークフローは、公開されている使い捨てのプライマリボードとセカンダリボード hUaItfNq および r9BpowfZ に固定されており、TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1 を設定します。そのため、Trelloでいずれかのボードが公開状態でなくなった場合、IDの出力や書き込みの前に失敗します。省略可能な domains および tools 入力を受け付け、コマンドによって生成された場合は reports/live-regression.json をアップロードします。別のボードを使用する場合は、コマンドをローカルで実行し、非公開ボードのレポートを公開しないでください。このワークフローでも environment.deployment: false を設定しています。ライブ回帰テストはシークレットを使用する検証であり、アプリのデプロイではないためです。フォークからのプルリクエストにTrelloの認証情報を渡してはいけません。ライブ回帰テストは workflow_dispatch または、シークレットを明示的に使用する別のワークフローで実行してください。

Release ワークフローは、main および v*.*.* タグへのプッシュ時に、公開用のマルチアーキテクチャ Docker イメージを linux/amd64 と linux/arm64 向けにビルドします。また、push=false を指定してブランチから手動実行し、リリース用イメージの変更をマージする前に、プッシュを行わないマルチプラットフォーム検証を実行することもできます。ドライランでは push=false のままにしてください。push=true を使用するのは、意図的に GHCR へ公開する場合に限ります。

使用例

MCP クライアントに接続したら、自然言語でTrelloの操作を依頼できます。

提案、承認、検証の各段階を明示した、確認を先に行う複数ツールのシーケンスについては、ワークフローガイドを参照してください。

Show me my Trello boards.
Show me the lists on my job scout board.
Show me the cards in my "Today" list.
Create a card called "Review invoices" in the bookkeeping list.
Move this card to Done.
Archive the card about the old onboarding checklist.
Show the recent activity for this card.
Add a comment to this card saying the invoices are ready for review.
Edit this card comment to include the updated invoice total.
Add this public URL as an attachment to the card.
Upload the file invoice.pdf from my Trello upload folder to this card.
Show me the custom fields configured on this board.
Set this card's Priority custom field to the High option.
Clear this card's Estimate custom field.

正確な表現はMCPクライアントによって異なります。サーバーはまずボードとボードリストを検出し、そのIDをカードのワークフローに使用できます。

Trello の大きなレスポンス

コレクションツールは、MCP クライアントが不必要に大きなペイロードを受け取らないよう、デフォルトで簡潔な Trello の読み取りを行います。大量のカード、ラベル、アクションを読み取る場合、デフォルトの limit は 50 です。Trello では、これらのコレクションの読み取りに 1000 の上限が設定されています。

ワークフローに必要なプロパティだけをリクエストするには、fields を使用します。オブジェクト名、ID、アクションタイプを検証するツールでは、より少ないフィールドセットをリクエストしても、スキーマで必須のフィールドが自動的に追加されます。レスポンスが大きくても有用な詳細確認の読み取りに限り、fields: "all" を使用してください。

カードコレクションツールとアクションツールでは、since と before を使用して、古いまたは新しい Trello オブジェクトをページ分割して取得できます。これらのカーソルには、ISO-8601 タイムスタンプ、Trello/Mongo ID、または Trello が対応している場合は null を指定できます。アクションの読み取りでは、Trello のアクションページネーション用に、0 から始まる page も利用できます。

範囲を限定したアクティビティの監査には、card_actions、board_actions、list_actions、workspace_actions を使用します。コメントに絞り込むには filter: "commentCard"、より広範なアクティビティを対象にするには filter: "all" を設定します。また、limit、since、before、page を組み合わせると、ボード、リスト、カード、ワークスペースの履歴を MCP クライアントで扱いやすいサイズに保てます。

メンバーを返すツールは、デフォルトで簡潔なメンバーフィールド（username,fullName,initials,avatarUrl）を返します。ワークフローで追加のメンバープロフィールプロパティが必要な場合は、fields、memberFields、memberCreatorFields などのメンバーフィールド入力を使用します。

検索

ユーザーから自然言語の検索語が提示され、アクションを実行する前に一致するカードやボードを探す必要がある場合は、search を使用します。デフォルトではカードとボードを検索し、簡潔なフィールドを返します。リソースタイプごとのデフォルトの結果数は 10 件です。メンバーまたはワークスペースの結果タイプが必要な場合は、modelTypes に members または organizations を追加します。

カードとボードの検索範囲を絞るには、boardIds: "mine" または特定のボード ID を使用します。ワークスペース ID には organizationIds を使用します。また、クエリの範囲をさらに絞り込んだり、ページネーションしたりする必要がある場合は、cardIds、partial、cardsPage、およびタイプごとの limit 入力を使用します。名前またはユーザー名で担当者を検索するには、特にボードまたはワークスペースで範囲を指定する場合に、search_members を使用します。

添付ファイルのアップロード

公開 URL の添付ファイルは、追加設定なしで使用できます。ローカルファイルのアップロードは実装されていますが、MCP クライアントがサーバープロセスにサーバーのファイルシステムからファイルを読み取るよう要求するため、デフォルトでは無効になっています。

card_attachment_upload を有効にするには、サーバーが読み取り可能な絶対ディレクトリパスを TRELLO_ATTACHMENT_UPLOAD_ROOT に設定します。アップロードツールの filePath 値には、そのディレクトリからの相対パス、または引き続き設定済みのルート内に解決される絶対パスを指定できます。サーバーは realpath でシンボリックリンクを解決し、ディレクトリを拒否します。また、Trello へのリクエストを送信する前に、設定済みのルート外にあるファイルを拒否します。

ローカルの stdio で使用する場合：

TRELLO_ATTACHMENT_UPLOAD_ROOT=/Users/you/trello-uploads \
  TRELLO_API_KEY=your-key \
  TRELLO_TOKEN=your-token \
  TRANSPORT=stdio \
  node dist/index.js

Docker の場合は、アップロードディレクトリをコンテナにマウントし、ルートをコンテナ内のパスに設定します。

docker run --rm -p 127.0.0.1:3000:3000 \
  -v "$PWD/trello-uploads:/uploads:ro" \
  -e TRELLO_ATTACHMENT_UPLOAD_ROOT=/uploads \
  -e TRELLO_API_KEY=your-api-key \
  -e TRELLO_TOKEN=your-token \
  ghcr.io/enthouan/trello-mcp:latest

MCP クライアントは、このツールを通じてバイトデータを直接アップロードしません。代わりに、サーバーホストまたはコンテナ内に存在するファイルのパスを指定します。リモートサーバーの場合は、まずファイルを TRELLO_ATTACHMENT_UPLOAD_ROOT にコピーするか、そこにマウントしてください。

カスタムフィールド

カスタムフィールドの定義は Trello ボードに保存され、カードの値はカードの customFieldItems として公開されます。board_custom_fields を使ってボードレベルのフィールド定義とその ID を確認し、custom_field_options を使ってフィールドのドロップダウン／リストの選択肢を一覧表示し、card_custom_field_items を使ってカードに現在設定されている値を確認します。

書き込みツール card_custom_field_set は、フィールドごとに、型に応じた入力形式を受け取ります。

カスタムフィールドの型	入力形式	備考
text	{ "type": "text", "text": "Hello" }	プレーンテキストの値です。
number	{ "type": "number", "number": "42" }	Trello では数値を文字列として指定する必要があります。
date	{ "type": "date", "date": "2026-06-03T16:00:00.000Z" }	ISO-8601 形式の日付／時刻文字列である必要があります。
checkbox	{ "type": "checkbox", "checked": true }	サーバーは Trello が想定する文字列値を送信します。
list	{ "type": "list", "optionId": "<custom-field-option-id>" }	board_custom_fields または custom_field_options を使って選択肢の ID を確認します。

既存のカードのカスタムフィールド値を消去するには、card_custom_field_clear を使います。Trello では DELETE リクエストではなく、空の PUT リクエスト形式でカスタムフィールドの値を消去するため、値の設定とは別の操作になっています。

ボードの作成

board_create は、新しい Trello ボードを作成します。prefs_permissionLevel のデフォルト値は private です。ボードを Trello ワークスペース／組織に配置するには workspaceId を渡します。また、ワークスペース内で表示可能（org）または公開（public）する場合に限り、permissionLevel を明示的に設定してください。

API の対応状況

Trello REST API のグループごとの対応状況、後回しにしているエンドポイント群、現在の対象外項目については、docs/api-coverage.md を参照してください。

ツール一覧

77 個のツールが登録されています。名前、説明、主要な入力は allTools から生成されます。

名前	使用する場面	主な入力
auth_whoami	設定済みの API キーとトークンで認証される Trello メンバーを確認するための、読み取り専用の認証情報診断として使用します。	fields
auth_token_info	設定済みの Trello トークンの所有者、有効期限、権限を調べるための、読み取り専用の認証情報診断として使用します。トークンの作成、更新、取り消し、管理は行いません。	fields
list_boards	ユーザーからボード、リスト、カード ID、または Trello URL が提示されていない場合に、最初に使用します。認証済みの Trello メンバーが閲覧できるボードを返します。	filter, fields
board_create	新しい Trello ボードを作成するときに使用します。既定では非公開ボードを作成し、workspaceId でワークスペースに配置できます。明示的に指定できる公開範囲は、非公開、ワークスペース、公開のみです。	name, desc, workspaceId, permissionLevel
board_get	既知の Trello ボードを一覧表示または要約する前に、ボードの詳細、一般的なボード設定、またはラベル名が必要なときに使用します。	boardId, fields
board_field_get	prefs、labelNames、subscribed、name、description、URL など、特定のボードフィールドが必要なときに使用します。	boardId, field
board_actions	ボード全体の最近のアクティビティやコメントを監査するときに使用します。大きな履歴の取得範囲を制限するには、filter、limit、page、since、before、fields を使用します。	boardId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields
board_lists	既知の Trello ボード上のリストが必要なときに使用します。カードを一覧表示または作成する前に、適切なリスト ID を見つけられます。	boardId, filter, fields
board_cards	個人的な計画、レビュー、要約のために、既知の Trello ボード上のすべてのリストにあるカードが必要なときに使用します。	boardId, filter, fields, limit, since, before
board_custom_fields	Trello が返す場合はドロップダウン／リストの選択肢も含め、既知の Trello ボード上のカスタムフィールド定義を調べるときに使用します。	boardId
board_labels	ラベルを使ってカードを作成または更新する前に、ボードで使用できるラベルを確認するときに使用します。	boardId, limit, fields
board_members	カードの割り当てや共同作業の確認の前に、既知の Trello ボードにアクセスできるメンバーが必要なときに使用します。非公開ボードを閲覧できるトークンが必要です。	boardId, fields
board_memberships	既知の Trello ボードのメンバーシップ記録、メンバーの役割、権限の状況が必要なときに使用します。ボード管理者のみが行える操作を確認する場合は、admins フィルターを使用します。	boardId, filter, member, memberFields
list_workspaces	ユーザーが Trello のワークスペースの表示を求めている場合や、ボードまたはメンバーを詳しく調べる前にワークスペースを選ぶ必要がある場合に、最初に使用します。	filter, fields, paidAccount
workspace_get	表示名、説明、URL、ウェブサイト、ボード ID、設定など、基本的な Trello ワークスペースのメタデータが必要なときに使用します。	workspaceId, fields
workspace_boards	既知の Trello ワークスペース内のボードが必要なときに使用します。ユーザーがワークスペース内のボードを詳しく調べられます。	workspaceId, filter, fields
workspace_members	割り当て、監査、権限の確認の前に、既知の Trello ワークスペース内のメンバーが必要なときに使用します。	workspaceId, filter, fields
workspace_actions	Trello ワークスペース全体の最近のアクティビティやコメントを監査するときに使用します。大きな履歴の取得範囲を制限するには、filter、limit、page、since、before、fields を使用します。	workspaceId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields
member_get	メンバー検索またはボードメンバー一覧の後、割り当てや監査の前に、ID、ユーザー名、または me で Trello メンバーのプロフィールを確認するときに使用します。	memberId, fields
member_boards	ID、ユーザー名、または me で指定した既知の Trello メンバーに関連するボードが必要なときに使用します。結果は、設定済みのトークンで閲覧できるボードに限定されます。	memberId, filter, fields
member_cards	ID、ユーザー名、または me で指定した既知の Trello メンバーに割り当てられたカードが必要なときに使用します。非公開ボードのカードには、そのボードへのトークンアクセスが必要です。	memberId, filter, fields, limit, since, before
member_workspaces	ID、ユーザー名、または me で指定した既知のメンバーに関連する Trello ワークスペースが必要なときに使用します。結果は、ワークスペースの閲覧範囲と役割の権限によって制限されます。	memberId, filter, fields, paidAccount
list_get	カードを作成したりリストを変更したりする前に、既知の Trello リストのメタデータが必要なときに使用します。	listId, fields
list_create	既存のボードに新しい Trello リストを作成するときに使用します。	boardId, name, pos
list_update	Trello リストの名前を変更したり、位置を変更したり、アーカイブ状態を設定したりするときに使用します。	listId, name, closed, pos
list_archive	リストのカードを復元可能な状態に保ったまま、Trello リストをアーカイブまたはアーカイブ解除するときに使用します。	listId, closed
list_move_to_board	既存のリストとそのカードを別のボードに移動し、アクセスできるユーザーを変更します。現在のボード内で並べ替える場合は list_update を使用します。	listId, boardId
list_actions	リストの最近のアクティビティやコメントを監査するときに使用します。大きな履歴の取得範囲を制限するには、filter、limit、page、since、before、fields を使用します。	listId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields
card_get	編集または要約の前に、ID、短縮リンク、または URL で指定した Trello カード 1 枚の現在の詳細が必要なときに使用します。	cardId, fields
card_board	移動、ラベル付け、状況の要約の前に、既知の Trello カードが属するボードの情報が必要なときに使用します。	cardId, fields
card_list	移動またはステータス報告の前に、既知の Trello カードが属するリストの情報が必要なときに使用します。	cardId, fields
card_labels	追加／削除のワークフローで使うラベル ID も含め、現在カードに適用されているラベルを一覧表示するときに使用します。	cardId
list_cards	特定の Trello リスト内のカードが必要なときに使用します。大きなリストの取得範囲を制限するには、limit、since、before、fields を使用します。	listId, filter, fields, limit, since, before
card_create	ユーザーが既知のリストに新しい Trello カードを作成するよう求めたときに使用します。タイトル、説明、期限、メンバー、ラベルを指定できます。	listId, name, desc, due, pos, memberIds, labelIds
card_update	カードを移動せずに、タイトル、説明、期限、期限の完了状態、アーカイブ状態などのメタデータを変更するときに使用します。	cardId, name, desc, due, dueComplete, closed
card_due_date_set	他のカードメタデータを変更せずに、カードの期限を設定、解除、または完了済みにするときに使用します。due または dueComplete の少なくとも一方を指定してください。	cardId, due, dueComplete
card_position_set	現在のリスト内でカードの位置だけを変更するときに使用します。リストやボードも変更する場合は card_move を使用します。	cardId, pos
card_cover_set	カードカバーに既存の添付ファイル ID を設定したり、カバーの表示サイズを変更したり、現在の添付ファイルカバーを解除したりするときに使用します。	cardId, attachmentId, size, brightness
card_label_create_and_add	新しいボードラベルを作成し、このカードに適用します。既存のラベルには card_label_add を使用してください。この操作を繰り返すと重複が作成される場合があります。	cardId, name, color
card_delete	ユーザーが Trello カードの完全削除を明示的に求めた場合にのみ使用します。取り消し可能な削除には、代わりにアーカイブしてください。	cardId
card_move	カードを別のリストやボードに移動したり、位置を変更したりするときに使用します。一般的なカードメタデータの更新とは異なります。	cardId, listId, boardId, pos
card_archive	カードを復元可能な状態に保ったまま、アーカイブまたはアーカイブ解除するときに使用します。完全削除には使用しないでください。	cardId, closed
card_attachments	Trello の添付ファイルフィールドまたはフィルターで絞り込みながら、カードに添付されたファイルやリンクを一覧表示するときに使用します。	cardId, fields, filter
card_attachment_get	Trello が返す場合はアップロードのメタデータも含め、添付ファイル ID で既存のカード添付ファイル 1 件を調べるときに使用します。	cardId, fields, attachmentId
card_attachment_add_url	既存の公開 URL をカードに添付するときに使用します。ローカルファイルはアップロードしません。	cardId, url, name, setCover
card_attachment_upload	TRELLO_ATTACHMENT_UPLOAD_ROOT 内のサーバーローカルファイルを読み取り、その内容を新しいカード添付ファイルとして Trello に送信します。このルートが設定されていない場合は無効です。アップロードを繰り返すと重複が作成される場合があります。公開リンクには card_attachment_add_url を使用してください。	cardId, filePath, name, mimeType, setCover
card_attachment_delete	アップロードしたファイルとして Trello に保存されているものも含め、カードから添付ファイルを完全に削除します。この操作は元に戻せません。添付ファイルを削除せずにカバーを解除するには card_cover_set を使用してください。	cardId, attachmentId
card_checklists	現在カードにあるすべてのチェックリストと項目を表示するときに使用します。	cardId
card_checklist_create	別のチェックリストからコピーする場合も含め、既存のカードに新しいチェックリストを追加するときに使用します。	cardId, name, sourceChecklistId
card_checklist_update	Trello カードのチェックリスト名を変更したり、カード上でのチェックリストの位置を変更したりするときに使用します。name または pos の少なくとも一方を指定してください。	checklistId, name, pos
card_checklist_delete	カードからチェックリストとその項目をすべて完全に削除します。この操作は元に戻せません。項目を 1 つだけ削除するには card_checklist_item_delete を使用してください。	cardId, checklistId
card_checklist_item_create	カード上の既存の Trello チェックリストに新しい項目を追加するときに使用します。	checklistId, name, pos, checked, due, dueReminder, memberId
card_checklist_items	既定では完了済みと未完了の両方を含め、1 つの Trello チェックリスト内の項目を一覧表示するときに使用します。	checklistId, filter, fields
card_checklist_item_update	Trello カードのチェックリスト項目のテキスト、期限、メンバーの割り当て、完了状態、チェックリスト、または位置を編集するときに使用します。	cardId, checkItemId, name, state, checklistId, pos, due, dueReminder, memberId
card_checklist_item_set_checked	他の項目フィールドを変更せずに、Trello カードのチェックリスト項目にチェックを付けたり外したりするときに使用します。	cardId, checkItemId, checked
card_checklist_item_move	Trello のチェックリスト項目を、同じカード上の別のチェックリストまたは別の位置に移動するときに使用します。	cardId, checkItemId, checklistId, pos
card_checklist_item_delete	チェックリスト項目を 1 つ完全に削除します。この操作は元に戻せません。項目を残したまま完了済みにするには card_checklist_item_set_checked を使用してください。	cardId, checkItemId
card_custom_field_items	Trello カードに現在設定されているすべてのカスタムフィールド項目の値を読み取るときに使用します。	cardId
card_custom_field_set	custom_field_get で取得した既存の定義の型を使って、カードのカスタムフィールド値を設定または置き換えます。リストの選択肢 ID を調べるには custom_field_options を使用し、値を削除するには card_custom_field_clear を使用してください。	cardId, customFieldId, type, text, number, date, checked, optionId
card_custom_field_clear	ボードのフィールド定義を削除せずに、カードのカスタムフィールド値を 1 つ消去します。元に戻すには、以前の値を card_custom_field_set で設定する必要があります。	cardId, customFieldId
card_members	カードに割り当てられたメンバーを一覧表示するときに使用します。カードのボードへのトークンアクセスが必要です。メンバー出力を小さくするには fields を使用してください。	cardId, fields
card_member_add	Trello メンバー ID でカードにメンバーを割り当てるときに使用します。カードのボードへの書き込み権限と、そのボードで割り当て可能なメンバーが必要です。	cardId, memberId
card_member_remove	Trello メンバー ID でカードからメンバーの割り当てを解除するときに使用します。カードのボードへの書き込み権限が必要です。	cardId, memberId
card_comment_add	Trello カードに新しいコメントを追加し、そのコメントのアクションを返します。呼び出しを繰り返すとコメントが追加されます。既存のコメントを編集するには card_comment_update を使用してください。	cardId, text
card_comment_update	コメントアクション ID で既存の Trello カードコメントのテキストを編集するときに使用します。	actionId, text
card_comment_delete	アクション ID でカードコメントを完全に削除します。この操作は元に戻せません。代わりにテキストを編集するには card_comment_update を使用してください。	actionId
card_actions	カードの最近のアクティビティやコメントを監査するときに使用します。大きな履歴をページ分割するには、filter、limit、page、since、before、fields を使用します。	cardId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields
label_get	編集する前に、特定の Trello ラベルの現在の名前、色、またはボードが必要なときに使用します。	labelId
label_create	カードに適用する前に、Trello ボードに再利用可能な新しいラベルを作成するときに使用します。	boardId, name, color
label_update	カードへの割り当てを変更せずに、Trello ラベルの名前や色を変更するときに使用します。	labelId, name, color
label_delete	ボードラベルの完全削除を明示的に求められた場合にのみ使用します。削除すると、そのラベルを使用しているすべてのカードから削除されます。ラベルを保持したまま 1 枚のカードから割り当てを解除するには card_label_remove を使用してください。	labelId
card_label_add	ラベル ID で既存の Trello ラベルをカードに適用するときに使用します。	cardId, labelId
card_label_remove	ラベル ID で既存の Trello ラベルをカードから削除するときに使用します。	cardId, labelId
custom_field_get	Trello のカスタムフィールド定義を ID で 1 つ取得するときに使用します。型と、Trello が返すドロップダウン／リストの選択肢も含まれます。	customFieldId
custom_field_options	カードのリスト型カスタムフィールド値を設定する前に、Trello のドロップダウン／リスト型カスタムフィールドで使用できる選択肢を一覧表示するときに使用します。	customFieldId
search	Trello を検索し、トークンから閲覧できるカード、ボード、メンバー、ワークスペースをグループ化して返します。既定ではカードとボードを対象とします。scope と limit で結果を絞り、カードのページネーションには cardsPage を使用します。メンバーを絞り込んで検索するには search_members を使用してください。	query, modelTypes, boardIds, organizationIds, cardIds, cardFields, boardFields, memberFields, organizationFields, cardsLimit, boardsLimit, membersLimit, organizationsLimit, cardsPage, partial, includeCardBoard, includeCardList, includeCardMembers, includeBoardOrganization
search_members	名前またはユーザー名で Trello メンバーを検索するときに使用します。ボードまたはワークスペースで絞り込むこともできます。絞り込み検索には、そのボードまたはワークスペースへのトークンアクセスが必要です。	query, limit, boardId, organizationId, onlyOrgMembers
以下のコマンドでカタログを再生成します。

corepack pnpm docs:tools

アーキテクチャ

リクエストのライフサイクル、トランスポートと認証情報の境界、HTTP セッション、検証、レート制限、再試行、結果の処理については、trello-mcp の仕組みをお読みください。

MCP client
  -> stdio or Streamable HTTP transport
  -> MCP server and tool registry
  -> Trello tool handlers
  -> Trello REST client
  -> Trello REST API

• src/index.ts は stdio または HTTP トランスポートを起動します。
• src/server.ts は MCP サーバーを作成し、ツールを登録します。
• src/http-auth.ts は、HTTP MCP リクエストに対する任意の MCP_AUTH_TOKEN ベアラーチェックを適用します。
• src/trello/auth.ts は、読み取り専用の auth_whoami と auth_token_info 認証情報診断ツールを定義します。
• src/trello/client.ts は、Trello HTTP リクエスト、認証クエリパラメーター、再試行、レスポンスの解析を担当します。
• src/trello/boards.ts は、ボードの検出と、ボードレベルのリスト、カード、ラベル、メンバー、カスタムフィールドのツールを定義します。
• src/trello/workspaces.ts は、ワークスペースの検出、メタデータ、ボード、メンバーのツールを定義します。
• src/trello/members.ts は、メンバーのプロフィール、ボード、カード、ワークスペースの検索ツールを定義します。
• src/trello/lists.ts は、リストの作成、確認、更新、アーカイブ、移動のツールを定義します。
• src/trello/cards.ts は、添付ファイル、チェックリスト、メンバー、コメント、アクション、カードのカスタムフィールド項目用ヘルパーなど、カード関連のツールを定義します。
• src/trello/labels.ts は、ラベルの CRUD とカードへのラベル割り当てツールを定義します。
• src/trello/custom-fields.ts は、カスタムフィールドの定義とオプションの検索ツールを定義します。
• src/trello/search.ts は、カード、ボード、メンバー、ワークスペースの検索ツールを定義します。
• src/trello/fields.ts は、共有の Trello フィールドリスト検証ヘルパーを定義します。
• src/trello/types.ts には、Trello のレスポンススキーマが含まれます。
• src/utils/* には、ログ記録、エラーマッピング、ページネーション、ツール登録のヘルパーが含まれます。

セキュリティに関する注意事項

• Trello の認証情報は、環境または MCP クライアント設定に保存してください。
• ログでは、TRELLO_API_KEY、TRELLO_TOKEN、MCP_AUTH_TOKEN、認証ヘッダー、および一般的なキー／トークンのフィールドがマスキングされます。
• Trello API リクエストには HTTPS を使用します。
• HTTP MCP トラフィックに対する基本的な共有シークレットチェックを行うには、MCP_AUTH_TOKEN を設定してください。これは、HTTPS、リバースプロキシ認証、IP 許可リスト、慎重なホストバインディングの代わりにはなりません。
• ローカルファイルの添付ファイルのアップロードは、TRELLO_ATTACHMENT_UPLOAD_ROOT が設定されていない限り無効です。アップロードパスはそのディレクトリに制限されます。
• テストでは、実際の Trello 呼び出しの代わりにモックと注入されたフェッチャーを使用します。
• .env ファイルを公開したり、トークンを issue や PR に貼り付けたりしないでください。

セキュリティ、プライバシー、サポート

• 対応バージョン、脆弱性の報告、認証情報の取り扱いに関する要件、脅威モデルに関する注意事項については、SECURITY.md をご覧ください。
• セルフホスト環境でのデータの取り扱い、外部サービス、公開 issue におけるプライバシーのガイダンスについては、PRIVACY.md をご覧ください。
• サポート窓口、対応範囲、有用なバグ報告に必要な情報については、SUPPORT.md をご覧ください。

開発

依存関係をインストールします。

corepack enable
corepack prepare [email protected] --activate
corepack pnpm install --frozen-lockfile

プロジェクトを最初から再ビルドします。

corepack pnpm build:clean

ローカルチェックを実行します。

corepack pnpm verify

カバレッジのゲートを実行します。

corepack pnpm verify:coverage

オプトインの Trello ライブスモークテストを実行します。

TRELLO_LIVE_SMOKE=1 \
TRELLO_LIVE_SMOKE_BOARD_ID=your-disposable-board-id-or-short-link \
TRELLO_API_KEY=your-api-key \
TRELLO_TOKEN=your-token \
corepack pnpm smoke:live

ローカルでウォッチモードを実行します。

TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token corepack pnpm dev

Docker イメージをローカルでビルドします。

corepack pnpm docker:build

Codex Cloud 環境

Codex Cloud のタスクでは、エージェントの起動前にセットアップスクリプトが実行されます。また、タスクブランチでキャッシュ済みコンテナーを再開するときに、任意のメンテナンススクリプトを実行できます。Codex 環境設定では、次のリポジトリスクリプトを使用してください。

./scripts/codex/setup.sh

./scripts/codex/maintenance.sh

セットアップスクリプトは Corepack を有効にし、固定された pnpm バージョンを有効化します。pnpm-lock.yaml がある場合は --frozen-lockfile を指定して依存関係をインストールし、pnpm typecheck を実行します。メンテナンススクリプトは、キャッシュ済みコンテナーで依存関係の同期と型チェックを再度実行し、ブランチの変更によって古い依存関係が使われないようにします。

トラブルシューティング

まず、起動、stdio、HTTP セッション、Docker、Trello API、レート制限、添付ファイルの障害を境界ごとに診断する、包括的なトラブルシューティングガイドをご確認ください。

サーバーは起動しますが、MCP クライアントにツールが表示されません

• クライアントが正しいトランスポートを使用していることを確認してください。
• stdio の場合は、TRANSPORT=stdio を設定してください。
• HTTP の場合は、/healthz や /readyz ではなく、クライアントの接続先を /mcp にしてください。
• MCP クライアントのセットアップガイドに記載されている、クライアントごとの再起動または再読み込みの手順に従ってください。

Trello で認証情報が無効と表示されます

• MCP クライアントから auth_whoami ツールと auth_token_info ツールを実行し、認証済みのメンバーとトークンの有効期限および権限を確認してください。
• トークンが同じ Power-Up/API キーから生成されたことを確認してください。
• トークンが取り消されている場合は、再生成してください。

Docker Compose で .env が見つかりません

• .env.example を .env にコピーしてください。
• TRELLO_API_KEY と TRELLO_TOKEN に値を設定してください。
• .env はコミットしないでください。

Trello のレート制限に達しました

• クライアントは Trello への各リクエストの前に、トークンバケット方式の制限を使用します。TRELLO_RATE_LIMIT_CAPACITY は 1 つのバケットウィンドウで実行できるリクエスト数を制御し、TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS はバケットの補充頻度を制御します。
• Trello が HTTP 429 を返した場合、クライアントは指数バックオフで再試行します。TRELLO_RETRY_MAX_ATTEMPTS はリクエストの合計試行回数を制御し、TRELLO_RETRY_BASE_DELAY_MS は開始時の遅延とジッターの範囲を制御し、TRELLO_RETRY_MAX_DELAY_MS は各再試行の待機時間の上限を設定します。
• LOG_LEVEL=debug の場合、トークンバケットによる待機は trello rate limit wait としてログに記録されます。HTTP 429 の再試行は、warn レベルで trello request rate limited; retrying としてログに記録されます。これらのログには、メソッド、リソースの種類、リソース ID、試行回数、最大試行回数、ステータスコード、待機時間などの安全なメタデータが含まれます。Trello の認証情報、完全な URL、クエリ文字列、生のリクエストパスは含まれません。
• まず、プロンプトまたはワークフローの範囲を絞り込んでください。対象を 1 つのボードまたはリストに限定し、必要なフィールドのみをリクエストし、利用できる場合は limit、since、before、page を使用してください。また、より小規模な検索やフィルタリングした読み取りで済む場合は、LLM にすべてのカードを調べさせないでください。
• 大規模なワークフローでまだ頻繁に待機が発生する場合は、慎重に調整してください。共有トークンを使用している場合や、より控えめに動作させたい自動化の場合は、バケットを小さくします。

TRELLO_RATE_LIMIT_CAPACITY=50
TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS=10000

• 意図的に大規模なユーザー起点のワークフローでは、リクエストのバケットを増やさずに、再試行回数を増やすことができます。

TRELLO_RETRY_MAX_ATTEMPTS=5
TRELLO_RETRY_BASE_DELAY_MS=250
TRELLO_RETRY_MAX_DELAY_MS=5000

• Trello アカウントとトークンの実際の負荷を把握していない限り、TRELLO_RATE_LIMIT_CAPACITY を大幅に増やさないでください。容量を増やすと、LLM 主導の広範なワークフローによって、Trello のサーバー側の制限に早く達する可能性があります。
• 429 が繰り返し返された場合は、ワークフローを再試行する前に数分待ってください。

コントリビューション

PR を歓迎します。変更の範囲を絞り、動作を変更する場合はテストを追加し、シークレットやローカルのビルドおよびテストの出力をコミットしないでください。正式なドキュメントまたは公開ツールデータを変更した場合は、corepack pnpm docs:tools を実行し、正当なチェックイン対象の生成済みドキュメントミラーを含めてください。

PR を作成する前に、次を実行してください。

corepack pnpm typecheck
corepack pnpm lint
corepack pnpm build
corepack pnpm test

ライセンス

MIT ライセンスです。LICENSE を参照してください。