Skip to main content

MCPB Files (.mcpb)

An MCPB file (.mcpb) is a ZIP archive 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.

Looking for a higher-level overview and when to choose .mcpb vs a remote MCP URL? See the marketing comparison: .mcpb vs Remote MCP URL — which install path to pick. This page is the technical specification reference.

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 packages.

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 — an MCPB package 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") — include 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 vendoring 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 a hosted MCP server without packaging your own? Browse mcpbundles.com, enable a server in your workspace, and connect it with the MCP URL or one-click install links on the server page.

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.4.

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

{
  "manifest_version": "0.4",
  "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 layout​

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

Python layout​

bundle.mcpb (ZIP file)
├── manifest.json         # Required: manifest 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: icon

Binary layout​

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

UV Runtime (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 can 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.

The format supports both patterns. On MCPBundles, hosted servers connect through the MCP URL.

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 packs all dependencies.

Or use mcpbundles.com to enable hosted MCP servers with pre-configured tools from dozens of APIs — select the tools you want, configure authentication, and connect via the MCP URL.

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

Cloud-connected packages​

Some .mcpb packages ship a lightweight local proxy that forwards requests to a hosted backend. Your AI talks to the local process over stdio; the proxy calls the cloud service where credentials and tool execution live. That pattern gives automatic updates and centralized credential management without running a full server locally.

MCPBundles hosted servers use the same cloud model, but you connect with the MCP URL (or one-click install links on the server page) rather than an .mcpb file.

Installing .mcpb Files​

Claude Desktop (macOS and Windows) has native support — open a .mcpb file with a double-click, or drag it into Claude Desktop's Settings window. Claude reads the manifest, installs the server, and prompts for any credentials the package declares.

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

Other MCP-compatible tools (ChatGPT, Cursor, Windsurf, VS Code) connect with an MCP URL instead. On MCPBundles, copy the server URL from Quick Setup or use the client install links on the server page.

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 publishers (verified GitHub repos, vendor sites, or your organization's extension directory). 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 the package is a cloud-connected proxy, 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​

On MCPBundles: Browse mcpbundles.com, enable an MCP server, copy its MCP URL from Quick Setup, and paste it into your AI client (or use the one-click install link for your client).

Building or installing .mcpb packages: Use the official MCPB CLI to pack your own server, or install a package from a publisher that ships .mcpb files for Claude Desktop.