Skip to main content
MCPB is the secondary distribution path. Remote MCP servers are recommended for directory listing—see what to build.
This guide covers building an MCP Bundle (.mcpb) for internal use, private distribution, or as a foundation for submission to the Connectors Directory.

​
What is an MCPB?

An .mcpb file is a zip archive containing a local MCP server and a manifest.json. It enables single-click installation in Claude Desktop, similar to a browser extension. Key characteristics:
  • Runs locally on the user’s machine
  • Communicates via stdio transport
  • Bundles all dependencies
  • Works offline
  • No OAuth required
See the MCPB repository for the complete specification and the Desktop Extensions blog post for an architecture overview.

​
Local (MCPB) vs remote: which to build

Key difference: 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. For remote connector guidance, see building custom connectors.

​
Choose a language

Node.js is strongly recommended:
  • Ships 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.

​
Quickstart

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.

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

​
Add an icon

Icons are optional but recommended. Place icon.png in your bundle root and reference it in manifest.json. You can also provide multiple icon variants for different sizes and themes (light/dark mode). 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.

​
How users install your MCPB

Users can install three ways:
  1. Double-click the .mcpb file
  2. Drag and drop the .mcpb file into the Claude Desktop window
  3. Settings: Settings → Extensions → Advanced settings → Install Extension… → select the .mcpb file
All three open an installation UI where the user reviews extension details and permissions, configures required settings, grants permissions, and completes installation. Installation is per-user; each user installs separately on their own system. For the end-user installation experience and Team/Enterprise admin controls (organization management, allowlists, policy configuration), see Getting Started with Local MCP Servers on Claude Desktop.

​
Resources

MCPB framework MCP protocol Claude Desktop

​
Get help

Check repository discussions for community Q&A, follow release notes for updates, and review the examples for implementation patterns.

​
Ready for distribution

If you have a working MCPB and want broader distribution and discoverability, submit it to the Connectors Directory. See submitting to the directory for requirements including:
  • Mandatory tool annotations for all tools
  • Privacy policy requirements
  • Working examples that exercise each tool
  • Test credentials where applicable
  • The complete submission process and review timeline