Skip to main content

What is an .mcpb file?

.mcpb is a packaging format introduced by Anthropic for distributing MCP servers. Think of it like an app installer (.exe, .dmg, .pkg) but specifically for MCP servers.

Quick Summary​

The .mcpb file is a convenience installer that wraps an MCP URL for one-click installation in Claude Desktop. Instead of manually copying and pasting a URL, you download a .mcpb file and double-click it.

Both methods connect to the same bundle - the file format is just a user experience improvement.

Two Ways to Add Bundles​

You can add the same bundle to your AI using either method:

Method 1: MCP URL (Universal)​

Works in all MCP-compatible AI tools:

https://mcp.mcpbundles.com/bundle/your-bundle-name

Compatible with:

  • ChatGPT
  • Cursor
  • VS Code
  • Windsurf
  • Claude Desktop
  • Gemini Code Assist
  • Any MCP-compatible tool

How to use:

  1. Copy the MCP URL from the bundle page
  2. Paste it into your AI tool's MCP settings
  3. Done - tools are now available

Method 2: .mcpb File (Claude Desktop Only)​

Works only in Claude Desktop:

How to use:

  1. Download the .mcpb file from the bundle page
  2. Double-click the file (or install via Settings > Extensions > Install Extension)
  3. Claude Desktop automatically configures the bundle and prompts for your MCPBundles API key
  4. Done - tools are now available

What's Inside an .mcpb File?​

Based on the official specification, an .mcpb file is a ZIP archive containing:

  1. manifest.json - Bundle metadata conforming to the .mcpb spec (name, version, description, author, server configuration)
  2. Server Implementation - The actual MCP server code (in MCPBundles' case: a Node.js proxy that connects to our cloud)
  3. Dependencies - Required packages (e.g., @modelcontextprotocol/sdk for Node.js)
  4. README - Documentation about the bundle

What it does NOT contain:

  • Your credentials (prompted during installation)
  • The actual tool code (runs on MCPBundles cloud servers)
  • Any of your data

Cloud-Hosted vs Local MCP Servers​

This is an important distinction:

MCPBundles Approach (Cloud-Hosted)​

Your AI → .mcpb bridge → MCPBundles Cloud → API Tools

Advantages:

  • No local setup required
  • Automatic updates
  • Centralized credential management
  • Works across all your devices
  • No maintenance needed

Traditional MCP Servers (Local)​

Your AI → .mcpb package → Local server process → API Tools

When to use:

  • Running custom/private MCP servers
  • Need full control over execution
  • Working with local files/databases
  • Development and testing

Technical Details​

File Structure​

A .mcpb file is a ZIP archive. For MCPBundles, the structure looks like:

bundle-name.mcpb/
  ├── manifest.json           # Bundle metadata and config
  ├── package.json           # Node.js dependencies
  ├── node_modules/          # @modelcontextprotocol/sdk
  ├── server/
  │   └── proxy.js           # Node.js proxy to MCPBundles cloud
  └── README.md              # Documentation

Manifest Example​

MCPBundles generates manifests that look like this:

{
  "manifest_version": "0.1",
  "name": "marketing-automation",
  "display_name": "Marketing Automation",
  "version": "1.0.0",
  "description": "Email campaigns, CRM, and analytics tools",
  "author": {
    "name": "MCPBundles",
    "url": "https://mcpbundles.com"
  },
  "homepage": "https://mcpbundles.com/bundles/marketing-automation",
  "server": {
    "type": "node",
    "entry_point": "server/proxy.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/proxy.js"],
      "env": {
        "MCP_API_KEY": "${user_config.api_key}",
        "REMOTE_URL": "https://mcp.mcpbundles.com/bundle/marketing-automation/"
      }
    }
  },
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "MCPBundles API Key",
      "description": "Your personal API key from mcpbundles.com/dashboard/settings",
      "sensitive": true,
      "required": true
    }
  },
  "keywords": ["mcpbundles", "mcp", "api", "marketing"],
  "license": "MIT"
}

Proxy Server​

MCPBundles .mcpb files contain a Node.js proxy server that:

  1. Runs locally as an MCP server (using stdio transport)
  2. Connects to MCPBundles cloud via Streamable HTTP
  3. Forwards tool discovery and execution requests to the cloud
  4. Injects your API key for authentication

This architecture means:

  • The .mcpb file itself is small (~100KB)
  • Tool execution happens in the cloud with proper credential injection
  • Updates to tools happen on the server without reinstalling the .mcpb

FAQ​

Can I use .mcpb files in ChatGPT or Cursor?​

No. The .mcpb file format is specific to Claude Desktop's installation mechanism. For ChatGPT, Cursor, VS Code, Windsurf, and other AI tools, use the MCP URL directly.

Do I need to download the .mcpb file every time?​

No. Once installed in Claude Desktop, the bundle stays configured. The .mcpb file is only needed for initial setup.

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

Yes! Change the extension to .zip and extract it. You'll see the manifest, Node.js proxy server, MCP SDK dependencies, and documentation.

Are .mcpb files safe?​

MCPBundles-generated .mcpb files contain a Node.js proxy server that connects to our cloud service. The proxy runs locally on your machine but only forwards MCP requests to our secure cloud environment where actual tool execution happens.

Always download .mcpb files from trusted sources (like mcpbundles.com) and inspect them if you're unsure.

What if I want to modify a .mcpb file?​

You can extract and modify the files, but remember:

  • MCPBundles .mcpb files are designed to connect to our cloud service
  • Modifying them may break the connection
  • If you need custom behavior, consider using the MCP URL method with your own client

Why does the file size vary?​

MCPBundles .mcpb files are small (~100-500 KB) because they contain:

  • A manifest file (JSON, ~2 KB)
  • A Node.js proxy script (~10 KB)
  • The MCP SDK from npm (~100-400 KB compressed)
  • Optional README (Markdown, ~2-5 KB)

Other .mcpb files from different sources might be larger if they include full server implementations with more dependencies.

When to Use Which Method​

ScenarioRecommended Method
Using ChatGPTMCP URL
Using CursorMCP URL
Using Claude DesktopEither (.mcpb is easier)
Sharing with teamMCP URL (more universal)
Quick demo.mcpb file (one-click)
Programmatic setupMCP URL
Multiple AI toolsMCP URL

Next Steps​

Ready to install your first bundle? Choose your approach:

  1. Easy Mode: Download a .mcpb file from any bundle page → double-click → done
  2. Universal Mode: Copy the MCP URL → paste into your AI tool's settings → done

Both give you the same tools, same security, same cloud-hosted experience.