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

Choose MCPB when you needChoose a remote connector when you need
Access to systems behind your firewall (JIRA, Confluence, internal wikis, private databases)Cloud services and public APIs with centralized infrastructure
Authentication via existing SSO and browser sessions, no token managementOAuth flows with server-side token management
Zero-trust compliance inside corporate network boundariesDistribution across Claude on web, mobile, and desktop
Direct filesystem access for code editing and Git operationsCentralized updates pushed to all users
Integration with locally installed tools (Docker, IDEs, databases)Public-facing integrations used by multiple organizations
Hardware integration and desktop application control
Privacy-sensitive operations that should not leave the user’s machine
One-click install with bundled Node.js runtime, no dependencies to manage
No cloud infrastructure, VPN configuration, or firewall rules
Organization-level admin controls (custom uploads, allowlists)
Full control over authentication, authorization, and audit logs
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

npm install -g @anthropic-ai/mcpb
2

Create your MCP server

Build a stdio MCP server using the MCP SDK.
3

Generate the manifest

mcpb init
4

Bundle

mcpb pack
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.
Reference
MCPB Manifest SpecFull schema with all fields
Example manifestsReal-world implementations
CLI documentationCommand reference

​
Add an icon

Icons are optional but recommended. Place icon.png in your bundle root and reference it in manifest.json.
RequirementValue
File nameicon.png (or a custom path)
Size512×512px recommended (minimum 256×256px)
FormatPNG with transparency
LocationBundle root or specified path
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