build-mcpb

MCPB をビルドする（バンドルされたローカル MCP サーバー）

MCPB は、ランタイムと一緒にパッケージ化されたローカル MCP サーバーです。ユーザーはファイルを 1 つインストールするだけで、マシンに Node、Python、ツールチェーンがなくても実行できます。ローカル MCP サーバーを配布するための正式な方法です。

MCPB は二次的な配布方法です。Anthropic はディレクトリへの掲載にはリモート MCP サーバーを推奨しています。詳しくは https://claude.com/docs/connectors/building/what-to-build をご覧ください。

サーバーをユーザーのマシン上で実行する必要がある場合は MCPB を使います。ローカルファイルの読み取り、デスクトップアプリの操作、localhost サービスとの通信、OS レベルの API の利用などが該当します。サーバーがクラウド API を呼び出すだけなら、ほぼ間違いなく代わりにリモート HTTP サーバーを使うべきです（build-mcp-server を参照）。URL で済むものに MCPB のパッケージ化の負担をかけないでください。

---

MCPB バンドルの内容

my-server.mcpb              (zip archive)
├── manifest.json           ← identity, entry point, config schema, compatibility
├── server/                 ← your MCP server code
│   ├── index.js
│   └── node_modules/       ← bundled dependencies (or vendored)
└── icon.png

ホストは manifest.json を読み込み、server.mcp_config.command を stdio MCP サーバーとして起動し、メッセージをパイプで受け渡します。コードから見れば通常のローカル stdio サーバーと同じで、違いはパッケージ化だけです。

---

マニフェスト

{
  "$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
  "manifest_version": "0.4",
  "name": "local-files",
  "version": "0.1.0",
  "description": "Read, search, and watch files on the local filesystem.",
  "author": { "name": "Your Name" },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "ROOT_DIR": "${user_config.rootDir}"
      }
    }
  },
  "user_config": {
    "rootDir": {
      "type": "directory",
      "title": "Root directory",
      "description": "Directory to expose. Defaults to ~/Documents.",
      "default": "${HOME}/Documents",
      "required": true
    }
  },
  "compatibility": {
    "claude_desktop": ">=1.0.0",
    "platforms": ["darwin", "win32", "linux"]
  }
}

server.type — node、python、または binary です。情報を示すもので、実際の起動方法は mcp_config で指定します。

server.mcp_config — 起動するコマンド、引数、環境変数をそのまま指定します。バンドル内の相対パスには ${__dirname} を使い、インストール時の設定を置き換えるには ${user_config.<key>} を使います。自動で付加されるプレフィックスはありません。サーバーが読み取る環境変数名は、env に指定したものと完全に一致します。

user_config — ホストの UI に表示されるインストール時の設定です。type: "directory" はネイティブのフォルダー選択画面を表示します。sensitive: true は OS のキーチェーンに保存します。すべてのフィールドについては references/manifest-schema.md を参照してください。

---

サーバーコード：ローカル stdio と同じ

サーバー自体は標準的な stdio MCP サーバーです。ツールのロジックに MCPB 固有のものはありません。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { readFile, readdir } from "node:fs/promises";
import { join } from "node:path";
import { homedir } from "node:os";

// ROOT_DIR comes from what you put in manifest's server.mcp_config.env — no auto-prefix
const ROOT = (process.env.ROOT_DIR ?? join(homedir(), "Documents"));

const server = new McpServer({ name: "local-files", version: "0.1.0" });

server.registerTool(
  "list_files",
  {
    description: "List files in a directory under the configured root.",
    inputSchema: { path: z.string().default(".") },
    annotations: { readOnlyHint: true },
  },
  async ({ path }) => {
    const entries = await readdir(join(ROOT, path), { withFileTypes: true });
    const list = entries.map(e => ({ name: e.name, dir: e.isDirectory() }));
    return { content: [{ type: "text", text: JSON.stringify(list, null, 2) }] };
  },
);

server.registerTool(
  "read_file",
  {
    description: "Read a file's contents. Path is relative to the configured root.",
    inputSchema: { path: z.string() },
    annotations: { readOnlyHint: true },
  },
  async ({ path }) => {
    const text = await readFile(join(ROOT, path), "utf8");
    return { content: [{ type: "text", text }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

サンドボックス化はすべて自分で行う必要があります。 マニフェストレベルのサンドボックスはありません。プロセスはユーザーの完全な権限で実行されます。パスを検証し、ROOT の外へのアクセスを拒否し、起動対象を許可リストに登録してください。references/local-security.md を参照してください。

設定環境変数から ROOT をハードコードする前に、ホストが roots/list をサポートしているか確認してください。これはユーザーが承認したディレクトリを取得する、仕様に基づく方法です。実装パターンについては references/local-security.md を参照してください。

---

ビルドパイプライン

Node

npm install
npx esbuild src/index.ts --bundle --platform=node --outfile=server/index.js
# or: copy node_modules wholesale if native deps resist bundling
npx @anthropic-ai/mcpb pack

mcpb pack はディレクトリを ZIP 圧縮し、manifest.json をスキーマに照らして検証します。

Python

pip install -t server/vendor -r requirements.txt
npx @anthropic-ai/mcpb pack

依存関係をサブディレクトリにベンダー化し、エントリースクリプトでそのパスを sys.path の先頭に追加します。ネイティブ拡張機能（numpy など）はターゲットプラットフォームごとにビルドする必要があります。可能であればネイティブ依存関係は避けてください。

---

MCPB にサンドボックスはありません — セキュリティ対策は自分で行う必要があります

モバイルアプリストアとは異なり、MCPB は権限を強制しません。マニフェストに permissions ブロックはなく、サーバーはユーザーの完全な権限で実行されます。references/local-security.md は任意ではなく、必ず読む必要があります。プラットフォーム側で何も制限されないため、すべてのパスを検証し、すべての起動対象を許可リストに登録する必要があります。

マニフェストによるファイルシステムやネットワークの制限を期待してここに来たのであれば、そのような機能はありません。ツールハンドラーで自分で実装してください。

サーバーの役割がクラウド API の呼び出しだけなら、やめてください。それは MCPB の衣装をまとったリモートサーバーです。ローカルで実行してもユーザーに何のメリットもなく、理由もなくローカルセキュリティの負担を背負うことになります。

---

MCPB と UI ウィジェット

MCPB サーバーはリモート MCP アプリとまったく同じように UI リソースを提供できます。ウィジェットの仕組みはトランスポートに依存しません。実際のディスクを参照するローカルのファイル選択画面や、ネイティブアプリを操作するダイアログなどを作成できます。

ウィジェットの作成方法は build-mcp-app スキルで説明されています。ここでも同じように機能します。違いはサーバーの実行場所だけです。

---

テスト

# Interactive manifest creation (first time)
npx @anthropic-ai/mcpb init

# Run the server directly over stdio, poke it with the inspector
npx @modelcontextprotocol/inspector node server/index.js

# Validate manifest against schema, then pack
npx @anthropic-ai/mcpb validate
npx @anthropic-ai/mcpb pack

# Sign for distribution
npx @anthropic-ai/mcpb sign dist/local-files.mcpb

# Install: drag the .mcpb file onto Claude Desktop

リリース前に、開発用ツールチェーンのないマシンでテストしてください。MCPB で「自分のマシンでは動くのに」という問題が起きる場合、そのほとんどは実際にはバンドルされていない依存関係が原因です。

---

参考ファイル

• references/manifest-schema.md — manifest.json の全フィールドのリファレンス
• references/local-security.md — パストラバーサル、サンドボックス化、最小権限