Desktop Extensions(.mcpb)— Claude DesktopにMCPサーバをワンクリック導入

Desktop Extensionsは、Claude DesktopへローカルのMCPサーバを入れる配布形式です。MCP(Model Context Protocol)は、モデルとツールをつなぐ標準プロトコルです。サーバ本体と依存ライブラリを1つのzipにまとめ、manifest.jsonで起動方法と設定項目を宣言します。利用者は.mcpbファイルを選んで導入するだけで、JSONの手編集は要りません。

2025年6月26日に発表され、9月11日に拡張子が.dxtから.mcpb(MCP Bundle)へ変わりました。既存の.dxtは引き続き動作し、機能に差はありません。

気をつけたいのは、発表記事のサンプルと現行の仕様書が別物になっている点です。発表時の仕様バージョンは0.1で、リポジトリのMANIFEST.mdは0.3(2025年12月2日更新)です。ただ、差は版が進んだ結果ではありません。発表のサンプルが、仕様書のキー名と食い違っています。写して作ると、現行の仕様書と合わない書き方になります。違いは次の節で並べます。

組織で配る話は、後半の「組織で配るなら」で扱います。MCPの基本はMCP実用ガイド、MCPの呼び出し効率の話はMCPでコード実行する設計にあります。

発表のmanifestを写すと現行仕様とどこがずれるか

発表記事のmanifest.jsonは、現行のMANIFEST.mdと比べて次の点が違います。発表記事のサンプルは、リポジトリにある仕様0.1のスキーマとも一致しません。0.1のスキーマでも、バージョンキーはmanifest_versionです(旧名dxt_versionは非推奨)。OS別の上書きはplatform_overrides、プロンプトはtextが必須です。0.3と0.4で増えた主な点は、uvタイプ(0.4)などです。

uvタイプは、依存をpyproject.tomlに書いておき、Claude Desktop側がUVで解決する方式です。MANIFEST.mdによると、server/lib/やserver/venv/を含めてはいけません。バンドルは約100KBで済み、利用者のPythonインストールも要らないとされています。

発表の例に出てくるテンプレート変数にも差があります。発表は${TEMP}と${TMPDIR}を使っていますが、現行のMANIFEST.mdがmcp_configで挙げる変数は次の6つです。

• ${__dirname}:拡張の展開先
• ${HOME}:ホームディレクトリ
• ${DESKTOP}:デスクトップ
• ${DOCUMENTS}:ドキュメント
• ${DOWNLOADS}:ダウンロード
• ${pathSeparator}(別名${/}):パス区切り

${TEMP}は一覧にありません。これで動かなくなるとまでは言えず、Claude Desktopの実装は確認できていません。ただ、仕様書に載っている変数だけで組んでおくほうが、実装との食い違いを避けられます。なおmcpb_versionのままのmanifestを現行のClaude Desktopが受け付けるかどうかも、手元では確かめられていません。

導入の何が重かったのか

発表が挙げた摩擦は5つです。Node.jsやPythonなどの開発ツールが必要で、設定ファイルを手で書き換え、依存の衝突を自分で解き、有用なサーバはGitHubで探し、更新も手動で入れ直す、という流れでした。

設定ファイルはclaude_desktop_config.jsonで、置き場所はmacOSなら~/Library/Application Support/Claude/の下、Windowsなら%APPDATA%\Claude\の下です(MCP公式ドキュメントの記載)。Claude Codeの~/.claudeとは別の場所にあります。この手編集が、.mcpbの導入画面とmanifestのuser_configに置き換わったわけです。

.mcpbの中身と必須ファイル

実体は決まったレイアウトのzipです。Node.js拡張の例は次のとおりです。

extension.mcpb (ZIP archive)
├── manifest.json         # 拡張のメタデータと設定
├── server/               # MCPサーバ本体
│   └── index.js          # エントリポイント
├── node_modules/         # 同梱する依存パッケージ
├── package.json          # 任意:npmパッケージ定義
└── icon.png              # 任意:アイコン

必須なのはmanifest.jsonだけです。Pythonならserver/main.pyとlib/、バイナリならOSごとの実行ファイルをserver/に置きます。サーバのタイプはnode・python・binary、そして先ほどのuvの4つです。

ここに、見落としやすい非対称があります。Node.jsはClaude Desktopに同梱されますが、Pythonは同梱されません。発表と同じ内容を載せたリポジトリのREADMEも、利用者のPython導入を避けるためにNode.jsでの実装を勧めています。「利用者の前提インストールが不要」と言えるのは、Node.js拡張と、依存を同梱したバイナリ、uvタイプの場合です。依存をlib/に抱えるPython拡張を配るときは、この点を確認してください。

最小のmanifestと、使われるキー

現行仕様で必須のキーは、manifest_version・name・version・description・author・serverの6つです。authorの中はnameだけが必須です。

{
  "manifest_version": "0.3",
  "name": "my-extension",
  "version": "1.0.0",
  "description": "A simple MCP extension",
  "author": {
    "name": "Extension Author"
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"]
    }
  }
}

任意のキーには、表示名のdisplay_name、ストア向けの長い説明long_description、icons(ライトとダークで画像を分けられる)、privacy_policiesなどがあります。このうちprivacy_policiesは、外部サービスに利用者データを渡す拡張で必要とされています。多言語の文言はlocalizationに外出しでき、既定の置き場はmcpb-resources/${locale}.jsonです。

compatibilityでは、動かす条件を宣言できます。

"compatibility": {
  "claude_desktop": ">=1.0.0",
  "platforms": ["darwin", "win32", "linux"],
  "runtimes": { "node": ">=16.0.0" }
}

platformsの値はNode.jsのprocess.platformと同じdarwin・win32・linuxで、省略すれば全OS対象です。linuxを書けることと、Claude DesktopがLinuxで動くことは別の話です。発表は実装先をClaude for macOSとWindowsと書いており、Linux版への言及はありません。一方、ヘルプセンターのFAQにはLinuxでの保管先やパーミッションの記述があります。Linuxで使うなら、配布元の対応状況を確認してください。

利用者ごとの値をuser_configで受ける

APIキーや許可ディレクトリのような利用者ごとの値は、user_configに宣言します。Claude Desktopが入力画面を作り、値の保管まで受け持ちます。

{
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "API_KEY": "${user_config.api_key}"
      }
    }
  },
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "API Key",
      "description": "Your API key for authentication",
      "sensitive": true,
      "required": true
    }
  }
}

sensitive: trueの値はOSのキーチェーンで保管されます。ヘルプセンターの記載では、macOSはKeychain、WindowsはCredential Managerです。required: trueの項目が埋まるまでClaude Desktopは拡張を有効にしません。値は起動時に${user_config.api_key}の位置へ差し込まれます。

型はstring・number・boolean・directory・fileの5種類です。minとmaxで数値の範囲を縛れ、defaultには${HOME}・${DESKTOP}・${DOCUMENTS}が使えます。

multiple: trueを付けた項目をargsに書いたときの展開は、仕様書に例があります。利用者が2つのディレクトリを選ぶと、["${user_config.allowed_directories}"]が選んだパスごとの別々の引数に分かれます。ファイルシステム系のサーバで、許可ディレクトリを何個でも受けたいときにそのまま使える仕組みです。

仕様書は、秘匿値は環境変数で、パスや秘匿でないオプションはコマンド引数で渡すのが向くと述べています。

ツールとプロンプトの宣言

toolsとpromptsに拡張の機能を書くと、インストール前に何ができる拡張かが画面上で見えます。プロンプトは、現行仕様ではtextが要ります。

"tools": [
  { "name": "search_files", "description": "Search for files" }
],
"prompts": [
  {
    "name": "explain_code",
    "description": "Explain how code works",
    "arguments": ["code", "language"],
    "text": "Please explain the following ${arguments.language} code in detail:\n\n${arguments.code}"
  }
]

実行時にしか決まらないツールがあるサーバは、tools_generated: trueで「ここに列挙した以外にも増える」と宣言します。prompts_generatedも同じ形です。一方でMCPのリソースはmanifestに書きません。リソースは設定やファイルシステムの状態で変わるURIなので、宣言になじまないという理由が仕様書に書かれています。

パッケージ化から導入までの作業フロー

発表はinitとpackの2コマンドで説明しています。CLIドキュメントには、それ以外にvalidate・sign・verify・info・unsignもあります。

CLIドキュメントは署名を任意の手順として扱っています。署名の有無でClaude Desktopの表示や挙動がどう変わるかは、書かれていません。

拡張ディレクトリに載せる経路

一般の利用者は、同じ設定画面の「Browse extensions」から、Anthropicが審査した拡張を探して「Install」で入れます。必要な設定項目(APIキーなど)は導入時の画面で入力します。

載せたい開発者の流れは、提出フォームのガイドラインに沿って拡張を整え、WindowsとmacOSの両方で試し、提出し、Anthropic側の品質・セキュリティ審査を受ける、というものです。ヘルプセンターには、扱いの違う提出先も示されています。ローカルのデスクトップ拡張は専用の提出フォームから、プラグインやリモートコネクタは開発者ポータルからです。Claude Desktopで見るコネクタとの違いはコネクタのデスクトップ接続とWeb接続の使い分けで扱っています。

仕様とツールチェインはオープンソースで、Anthropicは他のAIデスクトップアプリへ同じ.mcpbが流通することを狙っています。リポジトリのREADMEは、拡張の形式をChromeの.crxやVS Codeの.vsixに近いものと説明しています。

組織で配るなら:allowlistと端末ポリシーのどちらで縛るか

Team・Enterpriseプランでは、OwnerまたはPrimary Ownerが組織の拡張を管理できます。統制は大きく3段に分かれ、効き方が違います。

allowlistの利用には、Claude Desktop 0.13.91以降が必要です。有効にした瞬間の挙動が、導入前に押さえておきたい点です。ヘルプセンターの記述では、次のことが起きます。

• すでにインストールされた拡張は、各クライアントから強制削除される
• 許可外の拡張は入れられなくなる
• .mcpbのドラッグや「Install Extension…」による個別導入もできなくなり、アプリ内レジストリだけが使える

削除された拡張は、利用者が入れ直す必要があります。ヘルプセンターは、業務時間外に設定を済ませることを勧めています。なお、allowlistは導入後に利用者がローカルのファイルを書き換える行為までは防げません。

自作の拡張を組織に配るときの条件も細かく決まっています。

• manifestのnameは、既存のどの拡張とも重ならない一意の値にする
• アップロードした拡張は、その組織専用で、他の組織では使えない
• 更新するときはversionを前回より上げ、nameは変えない。nameを変えると更新ではなく別の拡張として登録される

このnameの扱いは、manifestを書く段階から効いてきます。組織向けの拡張は、最初に決めたnameを後から変えにくいためです。

どの統制を選ぶか

状況別に見ると、選び方は次のようになります。

• 全社でClaude Desktopの拡張をまったく使わせない場合は、端末ポリシーでisDesktopExtensionEnabledをfalseにします。allowlistは出番がありません。
• 社内の拡張と少数の公開拡張だけを使わせる場合は、allowlistを有効にします。このとき端末ポリシーをfalseのままにしていると、allowlistが機能しない点に注意が必要です。
• ローカルMCPサーバそのものを禁じる場合は、別のキーisLocalDevMcpEnabledが担当します。これは拡張とは別の設定です。

ヘルプセンターは、拡張を企業で使う利点として、社内のwikiやJIRA、Confluenceなど、ファイアウォールの内側にあるシステムへVPN設定なしでつなげる点を挙げています。利用者の端末で動くので、既存のSSOやブラウザセッションの認証をそのまま使えるという説明です。

Claude Codeのプラグインやclaude mcp addとは何が違うか

Desktop Extensionsは「MCPサーバをClaude Desktopへ配る形式」です。MCPそのものではなく、Claude Codeのプラグイン機構(Claude Code Plugin / Marketplaceガイドを参照)とも別のレイヤにあります。同じMCPサーバを素のまま配ることも、.mcpbに包んで載せることも両立します。

Claude Code(v2.1.286で確認)側の登録方法は、claude mcp add --helpが示すとおりコマンドです。

claude mcp add my-server -e API_KEY=xxx -- npx my-mcp-server

--transportはstdio・sse・httpから選び、省略時はstdioです。--scopeはlocal・user・projectで、省略時はlocalになります。-eで渡す環境変数が、manifestのenvとuser_configの役割にあたります。

Claude Desktopの.mcpbでは、同じ指定をmcp_configとuser_configに宣言として書きます。利用者に見えるのは入力画面で、コマンドラインはありません。開発者が1回書いて、複数人の画面に同じ導入体験を届ける点が、コマンド登録との違いです。Claude Code全体の使い方はClaude Codeとは — できること・料金・使い方にあります。

Claude Codeで拡張を組み立てるときの指示

発表には、社内の実験的なMCPサーバをDesktop Extensionsで配っており、Claude Codeに組み立てさせるのが機能しているという記述と、渡すプロンプトの雛形があります。要点は、anthropics/mcpbのREADMEとMANIFEST.md、examplesを先に読ませること、manifest.jsonと@modelcontextprotocol/sdkによるサーバ実装、エラー処理とタイムアウトを作らせること、stdioでの通信とツールの戻り値まで検証させることです。

ここまでの違いを踏まえると、指示に一行足したくなります。「MANIFEST.mdの現行版(manifest_version 0.3)に合わせる」と明示することです。発表の雛形のまま依頼すると、読ませる仕様書と発表のサンプルが食い違い、どちらに合わせて書くかが曖昧になります。

まとめ

Desktop Extensionsを配る側は、発表記事ではなくMANIFEST.mdの現行版を基準にしてください。発表のサンプルと仕様書で、キー名やプロンプトの形が食い違っているためです。配る相手が組織なら、allowlistを入れる前に、端末ポリシーとの優先関係と、既存の拡張が強制削除される挙動を確認しておく必要があります。