Build a desktop extension with MCPB changedconnectors/building/mcpb
Nearest release: v2.1.283, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 25 Sep 2026 18:00 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 25 Sep 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+76added
Lines−70removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits2to this page, all time
## Decide when to build an MCPB ### Choose between MCPB and a remote connector ## Build the bundle ### Choose a language ### Platform support ### Create and pack the bundle ## Configure manifest.json ### Add an icon ### User configuration ## Distribute your MCPB ### Understand how users install your MCPB ## Get help with MCPB ## Related resources ### MCPB framework ### MCP protocol ### Claude Desktop ## Next steps ## What is an MCPB? ## Local (MCPB) vs remote: which to build ## Choose a language ## Platform support ## Quickstart ## manifest.json ## Add an icon ## User configuration ## How users install your MCPB ## Resources ## Get help ## Ready for distribution
The whole hunk
from line 1, old and new numbered
/
from line 1
11# Build a desktop extension with MCPB
22
3> Package a local MCP server as a single-click .mcpb install for Claude Desktop
3> Package a local MCP server as a single-click .mcpb install for Claude Desktop: when to build one, the CLI quickstart, manifest.json, and how users install it.
44
5<Note>
6 MCPB is the secondary distribution path. Remote MCP servers are recommended for directory listing—see [what to build](/docs/connectors/building/what-to-build).
7</Note>
5An 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.
86
9This guide covers building an MCP Bundle (`.mcpb`) for internal use, private distribution, or as a foundation for [submission to the Connectors Directory](/docs/connectors/building/submission).
7This 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.
108
11## What is an MCPB?
9For 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](/docs/connectors/building/what-to-build) explains.
1210
13An `.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.
11<Note>
12 * If you're building a remote server, see [Build an MCP server for Claude](/docs/connectors/building/index)
13 * If you're deploying desktop extensions across a Team or Enterprise organization, see [Install a local connector in the desktop app](/docs/connectors/custom/add-unlisted#install-a-local-connector-in-the-desktop-app)
14</Note>
1415
15Key characteristics:
16## Decide when to build an MCPB
1617
18An MCPB has these characteristics:
19
1720* Runs locally on the user's machine
1821* Communicates via stdio transport
1922* Bundles all dependencies
from line 23
2023* Works offline
2124* No OAuth required
2225
26MCPBs 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.
27
2328See the [MCPB repository](https://github.com/modelcontextprotocol/mcpb) for the complete specification and the [Desktop Extensions blog post](https://www.anthropic.com/engineering/desktop-extensions) for an architecture overview.
2429
25## Local (MCPB) vs remote: which to build
30### Choose between MCPB and a remote connector
2631
27| Choose MCPB when you need | Choose a remote connector when you need |
28| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
29| Access to systems behind your firewall (JIRA, Confluence, internal wikis, private databases) | Cloud services and public APIs with centralized infrastructure |
30| Authentication via existing SSO and browser sessions, no token management | OAuth flows with server-side token management |
31| Zero-trust compliance inside corporate network boundaries | Distribution across Claude on web, mobile, and desktop |
32| Direct filesystem access for code editing and Git operations | Centralized updates pushed to all users |
33| Integration with locally installed tools (Docker, IDEs, databases) | Public-facing integrations used by multiple organizations |
34| Hardware integration and desktop application control | |
35| Privacy-sensitive operations that should not leave the user's machine | |
36| One-click install with bundled Node.js runtime, no dependencies to manage | |
37| No cloud infrastructure, VPN configuration, or firewall rules | |
38| Organization-level admin controls (custom uploads, allowlists) | |
39| Full control over authentication, authorization, and audit logs | |
32The table lists the needs that point to each option.
4033
41**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.
34| Choose MCPB when you need | Choose a remote connector when you need |
35| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
36| Access to systems behind your firewall, such as your issue tracker, internal wikis, and private databases | Cloud services and public APIs with centralized infrastructure |
37| Authentication via existing SSO and browser sessions, no token management | OAuth flows with server-side token management |
38| Zero-trust compliance inside corporate network boundaries | Distribution across Claude on web, mobile, and desktop |
39| Direct filesystem access for code editing and Git operations | Centralized updates pushed to all users |
40| Integration with locally installed tools, such as Docker, IDEs, and databases | Public-facing integrations used by multiple organizations |
41| Hardware integration and desktop application control | |
42| Privacy-sensitive operations that should not leave the user's machine | |
43| One-click install with bundled Node.js runtime, no dependencies to manage | |
44| No cloud infrastructure, VPN configuration, or firewall rules | |
45| Organization-level admin controls, such as custom uploads and allowlists | |
46| Full control over authentication, authorization, and audit logs | |
4247
43Organizations commonly build MCPBs as secure proxies to internal MCP servers, for internal documentation access, and to connect development tools while preserving their security architecture.
48## Build the bundle
4449
45For remote connector guidance, see [building custom connectors](/docs/connectors/building/index).
50You 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.
4651
47## Choose a language
52### Choose a language
4853
49Node.js is strongly recommended:
54Node.js is strongly recommended, for these reasons:
5055
51* Ships with Claude Desktop on macOS and Windows, so users need no separate runtime
56* Included with Claude Desktop on macOS and Windows, so users need no separate runtime
5257* Best compatibility and reliability with Claude Desktop
5358* Extensive MCP SDK support
5459
55## Platform support
60### Platform support
5661
5762Claude 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.
5863
5964See the [manifest spec compatibility section](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md#compatibility) for platform and runtime requirement details.
6065
61## Quickstart
66### Create and pack the bundle
6267
68The MCPB CLI generates the manifest and packs the bundle.
69
6370<Steps>
6471 <Step title="Install the MCPB CLI">
6572 ```bash theme={null}
from line 101
94101 Before distributing your MCPB, review the testing and best-practices guidance in the MCPB README to ensure quality.
95102</Warning>
96103
97## manifest.json
104## Configure manifest.json
98105
99The `manifest.json` file is required metadata describing what your MCPB does, how to run it, which tools it provides, and what configuration it needs.
106The `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:
100107
101| Reference | |
108| Reference | Contents |
102109| ---------------------------------------------------------------------------------------- | --------------------------- |
103110| [MCPB Manifest Spec](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md) | Full schema with all fields |
104111| [Example manifests](https://github.com/modelcontextprotocol/mcpb/tree/main/examples) | Real-world implementations |
105112| [CLI documentation](https://github.com/modelcontextprotocol/mcpb/blob/main/CLI.md) | Command reference |
106113
107## Add an icon
114### Add an icon
108115
109Icons are optional but recommended. Place `icon.png` in your bundle root and reference it in `manifest.json`.
116Icons are optional but recommended. Place `icon.png` in your bundle root and reference it in `manifest.json`. The icon must meet these requirements:
110117
111| Requirement | Value |
112| ----------- | ----------------------------------------- |
113| File name | `icon.png` (or a custom path) |
114| Size | 512×512px recommended (minimum 256×256px) |
115| Format | PNG with transparency |
116| Location | Bundle root or specified path |
118| Requirement | Value |
119| ----------- | ---------------------------------------- |
120| File name | `icon.png`, or a custom path |
121| Size | 512×512px recommended, 256×256px minimum |
122| Format | PNG with transparency |
123| Location | Bundle root or specified path |
117124
118You can also provide multiple icon variants for different sizes and themes (light/dark mode). See the [manifest spec icons section](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md#icons) for variant syntax and best practices.
125You can also provide multiple icon variants for different sizes and for light and dark themes. See the [manifest spec icons section](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md#icons) for variant syntax and best practices.
119126
120## User configuration
127### User configuration
121128
122129Define a `user_config` section in `manifest.json` and Claude Desktop automatically generates a settings UI for your extension. The [manifest spec user configuration section](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md#user-configuration) covers the full schema, configuration types, validation constraints, sensitive-data handling, and multi-select patterns.
123130
124## How users install your MCPB
131## Distribute your MCPB
125132
126Users can install three ways:
133Users 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](/docs/plugins/overview).
127134
1281. **Double-click** the `.mcpb` file
1292. **Drag and drop** the `.mcpb` file into the Claude Desktop window
1303. **Settings**: Settings → Extensions → Advanced settings → Install Extension… → select the `.mcpb` file
135### Understand how users install your MCPB
131136
132All 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.
137Users can install your MCPB in any of these ways:
133138
134For 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](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop).
139* Double-click the `.mcpb` file
140* Drag and drop the `.mcpb` file into the Claude Desktop window
141* In Claude Desktop, go to **Settings > Extensions > Advanced settings > Install Extension…** and select the `.mcpb` file
135142
136## Resources
143Each 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.
137144
138**MCPB framework**
145For 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](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop).
139146
147## Get help with MCPB
148
149* [MCPB GitHub issues](https://github.com/modelcontextprotocol/mcpb/issues): bug reports and feature requests
150* [MCP specification repo](https://github.com/modelcontextprotocol/modelcontextprotocol): protocol questions
151* [Claude support](https://support.claude.com/en/articles/9015913-how-to-get-support): general Claude Desktop support
152
153## Related resources
154
155These external references cover the MCPB format, the MCP protocol, and Claude Desktop.
156
157### MCPB framework
158
140159* [MCPB repository](https://github.com/modelcontextprotocol/mcpb): complete specification and tools
141160* [MCPB Manifest Spec](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md): full manifest schema
142161* [MCPB CLI documentation](https://github.com/modelcontextprotocol/mcpb/blob/main/CLI.md): command reference
143162* [MCPB examples](https://github.com/modelcontextprotocol/mcpb/tree/main/examples): reference implementations
144163
145**MCP protocol**
164### MCP protocol
146165
147166* [MCP specification](https://modelcontextprotocol.io/docs/getting-started/intro): protocol documentation
148167* [MCP quickstart](https://modelcontextprotocol.io/docs/develop/build-server): getting-started guide
from line 168
149168* [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk): Node.js implementation
150169* [Python SDK](https://github.com/modelcontextprotocol/python-sdk): Python implementation
151170
152**Claude Desktop**
171### Claude Desktop
153172
154173* [Release notes](https://support.claude.com/en/articles/12138966-release-notes): version updates
155174* [Desktop Extensions blog](https://www.anthropic.com/engineering/desktop-extensions): architecture overview
156175
157## Get help
176## Next steps
158177
159* [MCPB GitHub issues](https://github.com/modelcontextprotocol/mcpb/issues): bug reports and feature requests
160* [MCP specification repo](https://github.com/modelcontextprotocol/modelcontextprotocol): protocol questions
161* [Claude support](https://support.claude.com/en/articles/9015913-how-to-get-support): general Claude Desktop support
162
163Check repository discussions for community Q\&A, follow release notes for updates, and review the examples for implementation patterns.
164
165## Ready for distribution
166
167If you have a working MCPB and want broader distribution and discoverability, submit it to the Connectors Directory. See [submitting to the directory](/docs/connectors/building/submission) for requirements including:
168
169* Mandatory tool annotations for all tools
170* Privacy policy requirements
171* Working examples that exercise each tool
172* Test credentials where applicable
173* The complete submission process and review timeline
178* [Install a local connector in the desktop app](/docs/connectors/custom/add-unlisted#install-a-local-connector-in-the-desktop-app): deploy local MCP servers for Claude Desktop across a Team or Enterprise organization
179* [Submit your plugin](/docs/plugins/submit): list a plugin that includes your local MCP server in the directory
174180
No line in this hunk matches that.