How to Build a Claude Desktop Extension (.mcpb): Step-by-Step

To build a Claude Desktop extension, write a local MCP server that talks over stdio, install the MCPB command-line tool with npm install -g @anthropic-ai/mcpb, run mcpb init to create a manifest.json, then run mcpb pack to produce a .mcpb file. Double-click the file to install and test it in Claude Desktop.

This tutorial walks through each step, including user settings for API keys, signing, and how to share the result now that Claude's directory no longer accepts standalone extensions. Commands and fields were checked against the MCPB repository, its CLI reference and manifest spec, and Anthropic's MCPB build guide on 2 November 2026. The two manifest examples were also run through mcpb validate and mcpb pack with @anthropic-ai/mcpb 2.1.2 on that date; installing in Claude Desktop was not part of that check.

Before you start

You need:

• A working local MCP server that uses the stdio transport. Anthropic's guide says to build it with the MCP TypeScript SDK. Our lessons on building a first tool in TypeScript or Python cover that part.
• Node.js and npm on your development machine, to install the CLI.
• Claude Desktop on macOS or Windows for testing.

Pick a language

Anthropic's build guide says "Node.js is strongly recommended" because it is "Included with Claude Desktop on macOS and Windows, so users need no separate runtime." The manifest also supports python, uv (Python with dependencies declared in pyproject.toml) and binary server types. Python extensions need the user's machine to have a suitable runtime unless you bundle one.

Step 1: Install the MCPB CLI

npm install -g @anthropic-ai/mcpb

The repository says the older @anthropic-ai/dxt package "will be moved" to @anthropic-ai/mcpb. Run mcpb help to see the commands. Version 2.1.2 lists init, validate, clean, pack, unpack, sign, verify, info and unsign.

Step 2: Lay out your project

Keep your server code in a folder inside the extension directory. A simple Node layout:

my-extension/
  manifest.json
  icon.png
  server/
    index.js
  node_modules/
  package.json

Bundle your dependencies. The extension must run on a machine that has never seen your project.

Step 3: Create the manifest

Run the interactive generator in your extension folder:

mcpb init

It asks questions and writes manifest.json. The manifest spec lists the required fields as manifest_version, name, version, description, author (with name) and server. The spec's current version is 0.3.

A minimal manifest, based on the spec's own example with its comments removed:

{
  "manifest_version": "0.3",
  "name": "my-extension",
  "version": "1.0.0",
  "description": "A simple MCP extension",
  "author": {
    "name": "Extension Author"
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"]
    }
  }
}

${__dirname} is replaced with the folder where Claude Desktop unpacks your extension.

Step 4: Add settings users fill in

Most servers need an API key or a folder path. Declare them in user_config. The spec supports the types string, number, boolean, directory and file, plus title, description, required, default and sensitive. You pass values to your server with ${user_config.KEY} in mcp_config.

An example with one secret:

{
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "API key",
      "description": "Your account API key",
      "sensitive": true,
      "required": true
    }
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "API_KEY": "${user_config.api_key}"
      }
    }
  }
}

Claude Desktop builds a settings screen from this. Anthropic's Desktop Extensions post says "Sensitive configuration like API keys are stored in the OS keychain."

Other fields worth adding

• compatibility: set platforms (darwin, win32) and runtime versions. Anthropic's guide says Claude Desktop runs on macOS and Windows and asks you to "Test on both platforms." Claude Desktop also has a Linux beta now, so add linux only if you have tested there.
• tools and prompts: list what your server offers so users see it before installing. Set tools_generated: true if your server creates tools at runtime.
• Icon: Anthropic's guide recommends a 512×512px PNG with transparency, 256×256px minimum.
• Privacy policy: Anthropic's submission guide says local connectors in its directory need a privacy_policies array in manifest.json for manifest_version 0.2 and later. Add one if you plan to distribute through a plugin.

Step 5: Validate and pack

Check the manifest against the schema, then build the bundle:

mcpb validate manifest.json
mcpb pack my-extension/ my-extension-v1.0.mcpb

The CLI reference says pack validates the manifest first. Run mcpb info my-extension-v1.0.mcpb to see the file size and signature status. Version 2.1.2 also has mcpb clean, which its help text says "minimizes bundle size."

Step 6: Sign the bundle

Signing lets users and admins confirm who built the file and that it has not changed. The CLI supports:

mcpb sign my-extension-v1.0.mcpb --cert cert.pem --key key.pem
mcpb verify my-extension-v1.0.mcpb

For testing only, mcpb sign my-extension-v1.0.mcpb --self-signed creates a self-signed certificate. mcpb verify warns when a file uses one. For anything you share, use a real certificate.

Step 7: Install and test

Double-click the .mcpb file, drag it into Claude Desktop, or use Settings > Extensions > Advanced settings > Install Extension…. Fill in the settings, then ask Claude to use each tool.

If the extension installs but shows no tools, the Claude help center's local MCP servers article suggests you "Restart Claude Desktop to refresh the extension registry." Before packing, it is faster to debug the bare server with the MCP Inspector.

Test checklist:

• Fresh install on a machine without your dev tools.
• Both macOS and Windows.
• Missing or wrong API key: does the server return a clear error?
• Paths with spaces in folder names.
• Upgrade from your previous version.

Step 8: Share it

Anthropic's build guide says "Users install the .mcpb file themselves in Claude Desktop" and that "the directory no longer accepts MCPB submissions." Your options:

• Private distribution. Host the file on your website or share it internally. Updates need a manual reinstall.
• Team or Enterprise. Owners can upload custom extensions for their organization, per the help center.
• Public directory. Include the local server in a Claude plugin and submit that.

For broader reach, also publish your server's metadata to the MCP Registry. See where to sell or list your MCP server.

Common mistakes

• Forgetting to bundle node_modules, so the server crashes on first launch.
• Writing logs to stdout, which breaks the stdio protocol. Log to stderr instead.
• Hard-coding an API key in the code instead of user_config.
• Declaring only darwin and then hearing from Windows users.
• Shipping a self-signed bundle to customers.

Next step

For the bigger picture on extensions and admin controls, read MCP desktop extensions explained. If you would rather have a signed, tested extension built for an internal system, talk to our MCP development team.

Frequently asked questions