DOCSEARCHbyAlgolia
Submit Docs

MCP Bundles (MCPB)

repository·main·Indexed 24 days ago

https://github.com/modelcontextprotocol/mcpb

A specification and toolchain for distributing local Model Context Protocol (MCP) servers as single-file .mcpb zip archives. It provides a CLI (@anthropic-ai/mcpb) to initialize and pack servers for single-click installation on platforms like Claude for macOS and Windows. Supports multiple runtime types including Node.js, Python, UV Runtime for automatic dependency management, and pre-compiled native binaries.

Tokens
13.3K
Snippets
28
Records
80
Agent score
84%

What's inside mcpb

  1. Overview of MCPB Examples

    main

    The examples/ directory contains reference implementations of MCP Bundles (MCPB). These examples are designed to demonstrate the MCPB manifest structure and provide templates for building your own extensions. They cover various runtimes including Node.js, Python, and compiled binaries.

    Note: These examples are NOT production ready. They are intended for demonstration, templating, and testing purposes only. They do not include the robust security measures required for production deployment.

  2. What is an MCP Bundle (MCPB)?

    main

    MCP Bundles (.mcpb) are zip archives that package a local MCP server along with a manifest.json file. The manifest describes the server's capabilities and configuration. This format is designed to enable single-click installation of local MCP servers in compatible applications, similar to how Chrome or VS Code extensions work.

    Note on Renaming: This project was formerly known as DXT (Desktop Extensions).

    • The dxt CLI is now mcpb.
    • .dxt files are now .mcpb files.
    • The @anthropic-ai/dxt package is moving to @anthropic-ai/mcpb.

  3. What is UV Runtime for MCP Bundles?

    main

    UV Runtime is a server type (server.type = "uv") that allows Claude Desktop to automatically manage Python environments and dependencies for an MCP extension.

    Key benefits include:

    • Automatic Python Management: Downloads the correct Python version for the user's platform.
    • Isolated Environments: Creates a virtual environment automatically.
    • Dependency Resolution: Installs dependencies directly from pyproject.toml using uv run.
    • Cross-Platform: Works on Windows, macOS, and Linux without requiring manual user setup.
    • Small Bundle Size: Since dependencies are not bundled into the package, the .mcpb file remains very small (e.g., ~2 KB).

  4. Choose and configure a server type

    main

    The server object defines how the MCP server is executed. Supported types include:

    • uv: A Python server using the UV runtime (v0.4+). It enables cross-platform support without bundling dependencies. Requires a pyproject.toml and must NOT include server/lib/ or server/venv/.
    • python: A Python server where all dependencies must be bundled within the MCPB (e.g., in server/lib or server/venv).
    • node: A Node.js server where all dependencies must be bundled in node_modules.
    • binary: A pre-compiled, self-contained executable. No runtime requirements are needed, and apps automatically append .exe on Windows.

  5. Structure of a binary MCP Bundle

    main

    A binary MCP bundle requires a manifest.json where server.type is set to "binary". The compiled executable should be placed in a server/ directory. Use a .mcpbignore file to exclude source code and build artifacts from the final bundle so that only the manifest and the executable are included.

    calculator-rust/
├── manifest.json       # server.type = "binary"
├── Cargo.toml          # Rust project
├── .mcpbignore         # Exclude source from bundle
└── src/
    └── main.rs         # Calculator MCP server (~80 LOC)

# After building, the `server/` directory is created with the compiled binary.

  6. Structure of a UV Runtime MCP Bundle

    main

    A UV Runtime bundle requires a specific directory structure to function correctly. The manifest.json must specify server.type = "uv" to trigger the automatic dependency management.

    Required files:

    • manifest.json: Defines the server type as uv.
    • pyproject.toml: Lists all Python dependencies required by the server.
    • .mcpbignore: Specifies files to exclude from the bundle build.
    • src/server.py: The actual MCP server implementation.
    hello-world-uv/
├── manifest.json       # server.type = "uv"
├── pyproject.toml      # Dependencies listed here
├── .mcpbignore        # Exclude build artifacts
└── src/
    └── server.py       # MCP server implementation

  7. Configure user settings with user_config

    main

    The user_config field allows you to define configurable options that the user can set (e.g., API keys, directories, or numeric limits).

    Each configuration item defines its type (e.g., string, directory, number), a title, a description, and whether it is required or sensitive. You can also set a default value.

    To use a user-configured value within your server's environment variables, use the ${user_config.key_name} syntax inside the server.mcp_config.env object.

    {
  "server": {
    "type": "node",
    "mcp_config": {
      "command": "node",
      "args": ["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
    }
  }
}

  8. Define user-facing configuration with user_config

    main

    The user_config field allows you to define configuration options that appear in the host application's UI. These values are collected from the user and can be injected into mcp_config using ${user_config.KEY}.

    Supported Configuration Types

    • string: Text input (use sensitive: true to mask input).
    • number: Numeric input (supports min and max validation).
    • boolean: Checkbox/toggle.
    • directory: Directory picker (supports multiple: true).
    • file: File picker (supports multiple: true).

    Array Expansion

    If a configuration uses multiple: true, using that key in the args array will expand it into multiple separate arguments. For example, ["${user_config.dirs}"] where dirs contains ['/a', '/b'] becomes ['/a', '/b'] in the final command execution.

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

  9. Handle dynamic tools and prompts with _generated flags

    main

    If your MCP server generates capabilities (tools or prompts) dynamically at runtime based on configuration, context, or discovery, you must use the _generated flags in your manifest. This informs implementing applications that the server provides more capabilities than what is explicitly listed in the manifest.

    Use these flags:

    • tools_generated: Set to true if the server generates additional tools beyond those listed in the tools array (default: false).
    • prompts_generated: Set to true if the server generates additional prompts beyond those listed in the prompts array (default: false).
    {
  "tools": [{ "name": "search", "description": "Search functionality" }],
  "tools_generated": true,
  "prompts_generated": true
}

  10. Use the binary server type for MCP Bundles

    main

    The binary server type is used to package pre-compiled native executables rather than source code. This is the recommended approach for languages like Rust, Go, or C/C++, or for performance-sensitive workloads that require no runtime dependencies (unlike node or uv types).

    Note: Binaries are platform-specific; you must provide a separate build for each target OS and architecture you wish to support.

  11. Compare UV Runtime vs. Python Runtime

    main

    When deciding how to bundle your MCP server, choose between uv and python types based on these characteristics:

    FeatureUV Runtime (server.type = "uv")Python Runtime (server.type = "python")
    DependenciesAuto-resolved from pyproject.toml via uv runMust be manually bundled in server/lib/
    Bundle SizeVery small (no bundled deps)Larger (includes all dependencies)
    SetupZero user setup; automatic environment creationRequires mcp_config with PYTHONPATH
    CompatibilityWorks on any platformLimited to pure Python (no compiled deps)

  12. Declare tools and prompts in the MCPB manifest

    main

    The MCPB manifest allows you to declare the tools and prompts your MCP server provides.

    Tools: List tools in a tools array. Each tool object should include a name and a description.

    Prompts: List prompts in a prompts array. Each prompt object must include:

    • name: The unique identifier for the prompt.
    • description (optional): A description of the prompt's purpose.
    • arguments (optional): An array of argument names available for use in the prompt text.
    • text: The prompt template. Use the syntax ${arguments.argument_name} to define placeholders for MCP Client-supplied arguments.

    Note on Resources: Resources are not included in the manifest because they are considered inherently dynamic and discovered at runtime.

    {
  "tools": [
    { "name": "search_files", "description": "Search for files" },
    { "name": "read_file", "description": "Read file contents" }
  ],
  "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}"
    }
  ]
}