Skip to main content

What is an .mcpb file?

MCP Bundles (.mcpb) are ZIP archives containing a local MCP server and a manifest.json that describes the server and its capabilities. The format is similar to Chrome extensions (.crx) or VS Code extensions (.vsix) — one file that gives your AI assistant new capabilities with a single click.

Originally developed by Anthropic as "Desktop Extensions," the format is now part of the open-source Model Context Protocol project. The specification, CLI tooling, and reference implementation are all open-source, enabling any AI desktop application to support .mcpb bundles.

Why This Matters​

Before .mcpb files, installing an MCP server meant dealing with different programming languages, dependency management, manual configuration files, and platform compatibility issues. Now you get:

  • One file containing everything needed to run a local MCP server
  • One click to install — no terminal, no config editing, no dependency conflicts
  • Cross-client portability — a bundle built for one MCP-compatible application works in any other that implements the specification

The bigger picture: .mcpb is laying the groundwork for an AI-native app ecosystem. Claude Desktop already has a curated extension directory built in. Version management, automatic updates, and security scanning are already part of the format — the infrastructure that made mobile apps accessible is here for AI tools.

What You Can Package​

The format supports four server types:

  • Node.js (server.type = "node") — the recommended choice since Node.js ships with Claude Desktop, meaning zero external dependencies for users
  • Python (server.type = "python") — bundle all required packages in server/lib/ or a complete virtual environment
  • Binary (server.type = "binary") — pre-compiled executables, completely self-contained
  • UV Runtime (server.type = "uv", experimental) — Python via UV runtime, enabling cross-platform support without bundling dependencies. Dependencies are declared in pyproject.toml and the host application manages installation

People are packaging complete automation workflows, specialized industry tools, data connectors for popular APIs, and AI agents with specific expertise. The format handles all of them.

Want to skip the technical stuff? Browse and download pre-built .mcpb files from mcpbundles.com or build your own custom bundles using the platform's builder.

What's Actually Inside​

An .mcpb file is a ZIP archive with a specific structure. You can rename it to .zip and extract it to inspect everything inside.

The manifest.json is the key piece — it tells the host application exactly what tools and prompts this server exposes, what configuration the user needs to provide, and how to run it. The current manifest spec version is 0.3 (updated December 2025).

Here's what a manifest looks like with the required fields plus user configuration:

{
  "manifest_version": "0.3",
  "name": "my-mcp-server",
  "display_name": "My MCP Server",
  "version": "1.0.0",
  "description": "Does something useful",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "API_KEY": "${user_config.api_key}"
      }
    }
  },
  "tools": [
    {
      "name": "hello_world",
      "description": "A simple greeting tool"
    }
  ],
  "tools_generated": true,
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "API Key",
      "description": "Your API key for authentication",
      "sensitive": true,
      "required": true
    }
  },
  "license": "MIT"
}

Key manifest features:

  • mcp_config — defines how the host app launches the server, with variable substitution (${__dirname}, ${HOME}, ${user_config.*})
  • user_config — declares configuration the host collects from users (strings, numbers, booleans, directories, files). Sensitive values are stored in the OS keychain
  • tools / tools_generated — static tool declarations plus a flag indicating the server generates additional tools at runtime
  • prompts / prompts_generated — same pattern for prompt templates
  • compatibility — client version constraints, platform requirements (darwin, win32, linux), and runtime versions
  • localization — per-locale resource files for translated strings
  • icons — light/dark theme variants at multiple sizes
  • privacy_policies — required when the extension connects to external services that process user data
  • platform_overrides — platform-specific server configuration (different commands, args, or env vars per OS)

What's NOT in the file: your credentials, private data, or anything sensitive. Those get prompted during install and stored securely.

Directory Structures​

Node.js Bundle​

bundle.mcpb (ZIP file)
├── manifest.json         # Required: Bundle metadata and configuration
├── server/               # Server files
│   └── index.js          # Main entry point
├── node_modules/         # Bundled dependencies
├── package.json          # Optional: NPM package definition
└── icon.png              # Optional: Bundle icon

Python Bundle​

bundle.mcpb (ZIP file)
├── manifest.json         # Required: Bundle metadata and configuration
├── server/               # Server files
│   ├── main.py           # Main entry point
│   └── utils.py          # Additional modules
├── lib/                  # Bundled Python packages
├── requirements.txt      # Optional: Python dependencies list
└── icon.png              # Optional: Bundle icon

Binary Bundle​

bundle.mcpb (ZIP file)
├── manifest.json         # Required: Bundle metadata and configuration
├── server/               # Server files
│   ├── my-server         # Unix executable
│   ├── my-server.exe     # Windows executable
└── icon.png              # Optional: Bundle icon

UV Runtime Bundle (Experimental)​

bundle.mcpb (ZIP file)
├── manifest.json         # server.type = "uv"
├── pyproject.toml        # Dependencies
└── src/
    └── server.py

Two Ways .mcpb Files Can Work​

The format supports different architectures depending on what you're building.

Cloud-hosted servers (like what MCPBundles does) put a lightweight proxy in the .mcpb file that connects to a cloud service. Your AI talks to the local proxy, which forwards requests to the cloud where the real work happens. This means automatic updates, centralized credential management, and zero local maintenance.

Traditional local servers package the complete server implementation directly in the .mcpb file. When you install it, the full server runs on your machine. This approach makes sense when you need complete control over execution, you're working with local files or databases, or you're building custom/private servers that shouldn't touch the cloud.

MCPBundles uses the cloud approach because it's simpler for end users. But the format supports both patterns.

Creating Your Own .mcpb Files​

The official CLI tool makes packaging straightforward:

npm install -g @anthropic-ai/mcpb

cd your-mcp-server/

mcpb init    # Create manifest.json interactively
mcpb pack    # Package everything into a .mcpb file

That generates a .mcpb file ready to share. The CLI validates your manifest and bundles all dependencies.

Or use mcpbundles.com to build custom bundles with pre-configured tools from dozens of APIs — select the tools you want, configure authentication, and download your .mcpb file. No coding required.

The full specification is at github.com/modelcontextprotocol/mcpb, including the MANIFEST.md spec and examples.

MCPBundles Cloud Architecture​

When you download a .mcpb file from MCPBundles, here's what's actually inside: a small Node.js proxy server, the MCP SDK, and a manifest pointing to our cloud servers.

The proxy runs locally using stdio transport to talk to your AI. It connects to MCPBundles cloud via Streamable HTTP. When your AI asks what tools are available, the proxy forwards that question to the cloud. When you run a tool, the proxy sends the request to the cloud where we inject your credentials and execute the actual API call.

This architecture means tool updates happen on our servers without you reinstalling anything. The .mcpb file is just the bridge.

Installing .mcpb Files​

Claude Desktop (macOS and Windows) has native support — download a .mcpb file and double-click it, or drag it into Claude Desktop's Settings window. Claude automatically configures everything and prompts for any needed credentials.

Claude Code and MCP for Windows also support .mcpb bundles.

Other MCP-compatible tools (ChatGPT, Cursor, Windsurf, VS Code) don't support .mcpb files directly — they use MCP URLs instead. You can connect to the same servers by pasting the MCP URL into your AI's settings. Both methods connect to the same backend.

Security and Enterprise​

The .mcpb format includes several security features:

  • OS keychain storage — sensitive configuration like API keys are stored in the operating system's secure keychain, not in plain text
  • Automatic updates — extensions update automatically when new versions are published
  • Curated directory — Claude Desktop includes a built-in extension directory with reviewed extensions
  • Auditable — extract any .mcpb file and inspect all code inside

For enterprises, additional controls are available:

  • Deploy private extension directories
  • Disable the public extension directory entirely
  • Blocklist specific extensions or publishers
  • Pre-install approved extensions
  • Group Policy (Windows) and MDM (macOS) support

FAQ​

Can I inspect what's inside a .mcpb file?

Yes. Change the extension to .zip and extract it. You'll see everything — the manifest, server code, dependencies, docs, all of it.

Are .mcpb files safe?

Download from trusted sources (like mcpbundles.com or verified GitHub repos). The files don't contain credentials or personal data — those get added during installation and stored in the OS keychain. If you're unsure about a file, extract it and read the code.

Can I modify a .mcpb file?

You can extract and change whatever you want. If it's a cloud-connected proxy (like MCPBundles generates), modifying it might break the connection to the backend service.

Which AI tools support .mcpb files?

Claude Desktop (macOS and Windows), Claude Code, and MCP for Windows have native support. For ChatGPT, Cursor, VS Code, Windsurf, and other MCP clients, use the MCP URL method instead — same tools, different connection method.

Getting Started​

Browse pre-built .mcpb files at mcpbundles.com, download one, and double-click to install in Claude Desktop. Takes about 30 seconds.

Or build your own custom bundle on the platform — select the APIs and tools you need, configure everything visually, and download your personalized .mcpb file.