Skip to main content
An MCP Bundle (.mcpb) is a zip archive containing a local MCP server and a manifest.json, which Claude Desktop installs in a single click the way a browser installs an extension. The server runs on the user’s machine over stdio, so it can reach local files, locally installed tools, and systems behind the user’s firewall without any cloud infrastructure. This page is for developers packaging a local MCP server for Claude Desktop, whether for internal use or private distribution. It covers when to choose MCPB over a remote server, building and packing the bundle, the manifest, and how users install the result. For a directory listing, build a remote MCP server, which reaches people on every surface, or include the local server in a plugin, as Decide what to include in your plugin explains.

​
Decide when to build an MCPB

An MCPB has these characteristics:
  • Runs locally on the user’s machine
  • Communicates via stdio transport
  • Bundles all dependencies
  • Works offline
  • No OAuth required
MCPBs run on the user’s machine via stdio with access to local and internal resources. Remote connectors run on your servers via HTTPS and are accessed through Anthropic’s infrastructure. Organizations commonly build MCPBs as secure proxies to internal MCP servers, for internal documentation access, and to connect development tools while preserving their security architecture. See the MCPB repository for the complete specification and the Desktop Extensions blog post for an architecture overview.

​
Choose between MCPB and a remote connector

The table lists the needs that point to each option.

​
Build the bundle

You write a stdio MCP server, generate a manifest with the MCPB CLI, and pack both into a .mcpb file. Choose the language and target platforms before you start.

​
Choose a language

Node.js is strongly recommended, for these reasons:
  • Included with Claude Desktop on macOS and Windows, so users need no separate runtime
  • Best compatibility and reliability with Claude Desktop
  • Extensive MCP SDK support

​
Platform support

Claude Desktop runs on macOS (darwin) and Windows (win32). Specify supported platforms in the compatibility section of your manifest.json. Test on both platforms even if you primarily develop on one. See the manifest spec compatibility section for platform and runtime requirement details.

​
Create and pack the bundle

The MCPB CLI generates the manifest and packs the bundle.
1

Install the MCPB CLI

2

Create your MCP server

Build a stdio MCP server using the MCP SDK.
3

Generate the manifest

4

Bundle

5

Install and test in Claude Desktop

Double-click the generated .mcpb file.
For detailed implementation guidance, see the MCPB repository, the examples directory including a Hello World, and the README “For Bundle Developers” section.
Before distributing your MCPB, review the testing and best-practices guidance in the MCPB README to ensure quality.

​
Configure manifest.json

The manifest.json file is required metadata describing what your MCPB does, how to run it, which tools it provides, and what configuration it needs. These references document it:

​
Add an icon

Icons are optional but recommended. Place icon.png in your bundle root and reference it in manifest.json. The icon must meet these requirements: You can also provide multiple icon variants for different sizes and for light and dark themes. See the manifest spec icons section for variant syntax and best practices.

​
User configuration

Define a user_config section in manifest.json and Claude Desktop automatically generates a settings UI for your extension. The manifest spec user configuration section covers the full schema, configuration types, validation constraints, sensitive-data handling, and multi-select patterns.

​
Distribute your MCPB

Users install the .mcpb file themselves in Claude Desktop. Desktop extension listings in the directory are deprecated, and the directory no longer accepts MCPB submissions. To distribute a local MCP server through the directory, include it in a plugin.

​
Understand how users install your MCPB

Users can install your MCPB in any of these ways:
  • Double-click the .mcpb file
  • Drag and drop the .mcpb file into the Claude Desktop window
  • In Claude Desktop, go to Settings > Extensions > Advanced settings > Install Extension… and select the .mcpb file
Each of these install methods opens an installation UI where the user reviews extension details and permissions, configures required settings, grants permissions, and completes installation. Installation is per-user, so each user installs separately on their own system. For the end-user installation experience and Team and Enterprise admin controls, such as organization management, allowlists, and policy configuration, see Getting Started with Local MCP Servers on Claude Desktop.

​
Get help with MCPB

These external references cover the MCPB format, the MCP protocol, and Claude Desktop.

​
MCPB framework

​
MCP protocol

​
Claude Desktop

​
Next steps