brandpilot-mcp

brandpilot-mcp

BrandPilot 用の MCP サーバーです。ブランドをコーディングエージェントに取り込み、ブランドの一覧表示、デザインのコンテキストと継続用コントラクトの確認、リポジトリのルールパックとトークンのインストール、デザインシステムキットの取得を、Claude Code、Codex、Cursor、Claude Desktop、その他の MCP クライアントからネイティブに行えます。

このパッケージは、次のいずれかのモードで動作します。

• ワークスペース API キーを使用する場合（BRANDPILOT_API_KEY）：ホスト型の BrandPilot MCP（https://brandpilot.dev/api/mcp）への薄い stdio プロキシとして動作します。すべての tools/list、tools/call、prompts/list、prompts/get を転送して応答を中継するため、ツールの一覧は常に BrandPilot がその時点で提供しているものになります。パッケージを更新しなくても、新しいツールが追加されます。
• キーがない場合：アカウントもキーも不要で、BrandPilot REST API v2 経由で公開デザインシステムのツールを提供します。

データベースには一切アクセスしません。brandpilot.dev にネットワーク接続できるマシンであれば実行できます。Node.js 20 以降が必要です。

API キーを使って接続する

BrandPilot の Settings, API keys でワークスペース API キーを作成します。キーは bp_live_ で始まります。以下の bp_live_your_key_here を作成したキーに置き換え、コミットするファイルには保存しないでください。

Claude Code

claude mcp add brandpilot --scope user -e BRANDPILOT_API_KEY=bp_live_your_key_here -- npx -y brandpilot-mcp

次に、Claude Code で /mcp を実行して brandpilot が接続されていることを確認し、「BrandPilot に自分のことを尋ねて、ブランドの一覧を表示して」と依頼します。

Codex

codex mcp add brandpilot --env BRANDPILOT_API_KEY=bp_live_your_key_here -- npx -y brandpilot-mcp

または、~/.codex/config.toml に追加します。

[mcp_servers.brandpilot]
command = "npx"
args = ["-y", "brandpilot-mcp"]

[mcp_servers.brandpilot.env]
BRANDPILOT_API_KEY = "bp_live_your_key_here"

キーをファイルに保存しないようにするには、シェルで BRANDPILOT_API_KEY をエクスポートし、env テーブルの代わりに env_vars = ["BRANDPILOT_API_KEY"] を使用します。

Cursor

~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1 つのプロジェクト）に追加します。

{
  "mcpServers": {
    "brandpilot": {
      "command": "npx",
      "args": ["-y", "brandpilot-mcp"],
      "env": {
        "BRANDPILOT_API_KEY": "bp_live_your_key_here"
      }
    }
  }
}

その他の MCP クライアント

BRANDPILOT_API_KEY を環境変数に設定し、stdio サーバーとして npx -y brandpilot-mcp を実行します。同じ形式は、Claude Desktop の claude_desktop_config.json でも使用できます。

エラーの意味

メッセージ	原因	対処方法
BrandPilot が API キーを拒否しました（HTTP 401）	キーの入力ミス、有効期限切れ、または失効	新しいキーを作成してサーバーを再起動します
API キーにこの呼び出しに必要な権限がありません（HTTP 403）	キーに必要なスコープがありません（例：読み取り専用キーで finish_external_design を呼び出している）	そのスコープを持つキーを使用します
ホスト型の BrandPilot MCP が有効になっていません（HTTP 404）	その BrandPilot インスタンスでホスト型 MCP がまだ有効になっていません	それまでの間は BRANDPILOT_API_KEY の設定を解除して公開ツールを使用するか、BRANDPILOT_MCP_URL を確認します
N 秒以内に応答がありませんでした	ホスト型の呼び出しに BRANDPILOT_TIMEOUT_MS を超える時間がかかりました	再試行します。時間のかかる呼び出しの場合はタイムアウトを延長します

キーは Authorization ヘッダーでのみ送信され、エラーメッセージや stderr を含め、出力されることはありません。

ツール

API キーモードでは、ツールとプロンプトはホスト型サーバーから提供されます（ブランド、デザインコンテキスト、リポジトリのルールパック、デザインシステムキット、完成した作業のレビューへの取り込みなど）。最新の一覧は https://brandpilot.dev/api/v2/mcp/tools および brandpilot.dev/docs で確認できます。最初の呼び出しには whoami がおすすめです。

キーがない場合、サーバーは以下の公開ツールをすべて BrandPilot REST API v2 経由で提供します。

ツール	認証	機能
list_public_systems	なし	公開デザインシステムの一覧を取得します（名前、表示名、ブランドカラー、ステータス、バージョン、v2 エンドポイント）
get_system_manifest	なし	公開システムの完全な導入マニフェストを取得します。トークン、コンポーネント、ページ、ブランドアセット、デザイン方針を含みます
export_system_tokens	なし	システムのトークンをエクスポートします（globals-css、colors-ts、spacing-ts、typography-ts、tailwind-theme、tailwind-v4、brand-manifest、dtcg）
get_adoption_brief	なし	Markdown 形式のオンボーディングドキュメントです。デザインパッケージを初期化し、デザインラウンドを実施します（Claude Code では Design キャンバス、その他のエージェントではローカル HTML の下書き）

0.x からのアップグレード

ツールと環境変数が削除されたため、1.0.0 はメジャーリリースです。BrandPilot API v1 とデザインごとのハンドオフキーは 2026-12-15 に応答を停止します（HTTP 410）。そのため、0.x のすべてのインストールで、その日からキーなしの呼び出しができなくなります。それまでにアップグレードしてください。

• 公開ツールは API v1 と /api/systems/export/{name} の代わりに API v2（/api/v2/...、トークンの場合は /api/v2/systems/{name}/export）を呼び出すようになり、ホスト型サーバーで使われる v2 の名前を使用します。list_systems は list_public_systems に、get_system_adoption は get_system_manifest に、get_system_tokens は export_system_tokens に、get_agent_prompt は get_adoption_brief に変更されました。引数に変更はありません。export_system_tokens は tailwind-v4 と dtcg も受け付けます。
• get_adoption_brief は新しい v2 のブリーフを返します。Claude Code の場合は Design キャンバス上のデザインラウンド、その他のエージェントの場合はローカルの HTML ドラフトであり、Claude Design の手順ではありません。
• get_design_handoff、get_design_prompt_pack、import_design_artifacts、finish_external_design はキーなしサーバーから削除され、DESIGNFLOW_HANDOFF_KEY も読み取られなくなりました（値が残っている場合は、削除するよう求めるメッセージが1行だけ表示されます）。それらの v2 後継機能（get_design_context、get_design_brief、import_design_work、finish_design_import）はホスト型 MCP が提供します。BrandPilot でワークスペース API キーを作成し（Settings, API keys）、BRANDPILOT_API_KEY を設定してください。詳しくはAPI キーを使って接続するをご覧ください。
• Claude Design のプロンプトパックも廃止されます。claude.ai/design は 2026-12-14 に終了します。代わりに、ホスト型ツールはデザインのコンテキストと、自分のリポジトリで構築するためのリポジトリルールパックを返します。
• brandpilot-mcp/catalog がエクスポートするのは、v2 エンドポイントを使う4つの公開ツールのみになりました。

環境変数

変数	デフォルト値	用途
BRANDPILOT_API_KEY	(none)	ワークスペース API キー。プロキシモードを有効にします
BRANDPILOT_MCP_URL	${BRANDPILOT_ORIGIN}/api/mcp	プロキシモードでのホスト型 MCP エンドポイント。localhost を除き、https が必要です
BRANDPILOT_TIMEOUT_MS	70000	プロキシモードでのリクエストごとのタイムアウト（1000～600000）
BRANDPILOT_ORIGIN	https://brandpilot.dev	公開ツールのオリジン、およびデフォルトの BRANDPILOT_MCP_URL のベース。ローカルの開発サーバーを指定する場合に上書きします

ローカル開発

npm install
npm run build
npm test

E2E テストでは、API v2 に応答し、すべての v1 パスに 410 を返す偽のオリジンに対して、ビルド済みサーバーを実行します。ローカルの BrandPilot に対してテストを実行するには、npm test の前に BRANDPILOT_E2E_ORIGIN=http://localhost:3005 を設定してください（API v2 を提供する任意のオリジンを指定できます）。

ライブサーバーに対して最も手早く確認するには、npm link を実行し、リンクした bin を指定する MCP 設定を用意します。API キーモードでは whoami に自分のワークスペース名が表示されることを確認してください。キーなしの場合は、list_public_systems が厳選されたプールを返し、非公開の項目が含まれないことを確認してください。

リリースノートについては、CHANGELOG.md をご覧ください。