Skip to main content

What is an .mcpb file?

If MCP is the operating system for AI-native applications, then .mcpb is the application bundle format.

Think about how Windows has .exe files, macOS has .app bundles, and VS Code has .vsix extensions. The .mcpb format does the same thing for MCP servers - it packages everything you need to run an MCP server into a single portable file.

Created by Anthropic, this format solves a problem that was making MCP adoption harder than it needed to be. Before .mcpb files existed, installing an MCP server meant dealing with different languages, dependency conflicts, and manual configuration steps for every single setup. Now you just have one file that works everywhere.

Why This Matters​

Here's what changed. You can now package AI workflows, custom tools, autonomous agents, and domain-specific capabilities into a single file that anyone can install with a double-click. No setup, no dependencies to manage, no configuration headaches.

The bigger picture? This is laying the groundwork for an AI-native app ecosystem. Imagine marketplaces where you discover and install AI capabilities the same way you browse the App Store. Version management, security scanning, instant updates - all the infrastructure that made mobile apps explode is coming to AI tools.

You're not just downloading a file. You're participating in what could become the standard way AI capabilities get shared and distributed.

What You Can Package as .mcpb Files​

The format's flexible enough to handle pretty much any MCP server you can build. People are packaging complete automation workflows, specialized functions for specific industries, data connectors pre-configured for popular APIs, and even full AI agents with specific expertise baked in.

Some folks build custom servers for their teams and share them internally. Others are creating public .mcpb files that anyone can use. The format doesn't care - it just makes distribution frictionless either way.

Want to skip the technical stuff? You can 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 just a ZIP archive with a specific structure. You can rename it to .zip and unzip it if you're curious.

Inside you'll find the server code itself (could be Python, Node.js, whatever), a manifest.json file that acts as a contract defining what the server provides, any dependencies the server needs to run, and optional assets like icons or documentation.

The manifest is the key piece. It tells the host application exactly what tools this server exposes, what resources it can access, and what configuration the user needs to provide. This makes .mcpb files self-documenting - the host knows how to run them just by reading the manifest.

Here's what a basic manifest looks like:

{
  "manifest_version": "0.2",
  "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"
  },
  "tools": [
    {
      "name": "hello_world",
      "description": "A simple greeting tool"
    }
  ],
  "server": {
    "type": "node",
    "entry_point": "server/index.js"
  },
  "license": "MIT"
}

What's NOT in here: your actual credentials (those get prompted during install), your private data, or anything sensitive. The .mcpb file is just the server implementation.

Two Ways .mcpb Files Can Work​

The format supports different architectures depending on what you're trying to do.

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 itself supports both patterns.

Creating Your Own .mcpb Files​

Anthropic provides an official CLI tool that makes packaging straightforward:

# Install the tool
npm install -g @anthropic-ai/mcpb

# Go to your MCP server directory
cd your-mcp-server/

# Create the manifest
mcpb init

# Package everything
mcpb pack

That generates a .mcpb file ready to share.

Or if you prefer a visual interface, head to mcpbundles.com where you can 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 Complete Workflow​

Building an .mcpb-based workflow looks like this: create your MCP server with whatever tools and resources you need, pack it into an .mcpb file using the CLI or MCPBundles platform, distribute it however you want (GitHub releases, internal repos, direct downloads), let users install with one click in Claude Desktop or other MCP-compatible hosts, and the server automatically spins up with proper configuration.

Version updates? Just publish a new .mcpb file. Everything else stays the same.

Technical Deep Dive​

File Structure​

The ZIP archive typically has this layout:

my-server.mcpb/
  ├── manifest.json           # Server metadata and configuration
  ├── server/                 # Your server implementation
  │   └── index.js
  ├── package.json           # Dependencies (for Node.js servers)
  ├── node_modules/          # Bundled dependencies
  ├── icon.png               # Optional icon
  ├── assets/                # Optional additional resources
  └── README.md              # Documentation

The manifest defines the contract. The server directory contains your actual implementation. Everything else is supporting files.

MCPBundles Cloud Architecture​

When you download a .mcpb file from MCPBundles, here's what's actually in it: a small Node.js proxy server (around 10 KB), the MCP SDK (around 100-400 KB compressed), 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.

The Future of .mcpb​

We're watching the early stages of an AI-native app ecosystem take shape. Right now you can already build and share .mcpb files. Soon there'll probably be registries for discovering them, marketplaces for buying and selling specialized capabilities, and infrastructure for version management and security scanning.

If this plays out like other packaging formats, .mcpb could become as fundamental to AI development as Docker images are to containers or npm packages are to Node.js. The format is young but the trajectory's clear.

Installing .mcpb Files​

Claude Desktop has native support. Download a .mcpb file and double-click it, or go to Settings > Extensions > Install Extension. Claude will automatically configure everything and prompt for any needed credentials like your MCPBundles API key.

Other MCP-compatible tools (ChatGPT, Cursor, VS Code, Windsurf) don't support the .mcpb file format directly yet, but you can still use the same servers by connecting to them via MCP URLs instead.

FAQ​

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

Yep. 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) and you're fine. The files don't contain credentials or personal data - those get added during installation. If you're not sure about a file, extract it and check the code yourself. It's all readable.

Can I modify a .mcpb file?

Sure, extract it and change whatever you want. Just know that if it's a cloud-connected proxy (like MCPBundles generates), modifying it might break the connection to the backend service.

Does .mcpb work with tools other than Claude Desktop?

The file format itself is Claude Desktop specific right now. But most MCP servers also offer URL-based installation that works with ChatGPT, Cursor, VS Code, and other MCP-compatible tools. Check the server's docs for details.

Getting Started​

Want to try this out? Browse pre-built .mcpb files at mcpbundles.com, download one that looks useful, 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.

Either way, you're working with a format that could define how AI capabilities get distributed for years to come.