Desktop Extensions: One-click MCP server installation for Claude Desktop

Published: Jun 26, 2025

Update (Sep 11, 2025): Claude Desktop Extensions now use the .mcpb (MCP Bundle) file extension instead of .dxt. Existing .dxt extensions continue to work, but developers are recommended to use .mcpb for new extensions. All functionality remains the same — this is purely a naming convention update.

---

Desktop Extensions make installing MCP servers as easy as clicking a button. This article shares the technical architecture and tips for creating good extensions.

Addressing the MCP installation problem

Local MCP servers unlock powerful capabilities for Claude Desktop users. They can interact with local applications, access private data, and integrate with development tools — all while keeping data on the user's machine. However, the current installation process creates significant barriers:

• Developer tools required: Users need Node.js, Python, or other runtimes installed
• Manual configuration: Each server requires editing JSON configuration files
• Dependency management: Users must resolve package conflicts and version mismatches
• No discovery mechanism: Finding useful MCP servers requires searching GitHub
• Update complexity: Keeping servers current means manual reinstallation

These friction points meant that MCP servers, despite their power, remained largely inaccessible to non-technical users.

Introducing Desktop Extensions

Desktop Extensions (.mcpb files) solve these problems by bundling an entire MCP server — including all dependencies — into a single installable package. Here's what changes for users:

Before:

# Install Node.js first
npm install -g @example/mcp-server
# Edit ~/.claude/claude_desktop_config.json manually
# Restart Claude Desktop
# Hope it works

After:

1. Download a .mcpb file
2. Double-click to open with Claude Desktop
3. Click "Install"

No terminal, no configuration files, no dependency conflicts.

Architecture overview

A Desktop Extension is a zip archive containing the local MCP server as well as a manifest.json, which describes everything Claude Desktop and other apps supporting desktop extensions need to know.

extension.mcpb (ZIP archive)
├── manifest.json         # Extension metadata and configuration
├── server/               # MCP server implementation
│   └── [server files]
├── dependencies/         # All required packages/libraries
└── icon.png             # Optional: Extension icon

# Example: Node.js Extension
extension.mcpb
├── manifest.json         # Required: Extension metadata and configuration
├── server/               # Server files
│   └── index.js          # Main entry point
├── node_modules/         # Bundled dependencies
├── package.json          # Optional: NPM package definition
└── icon.png              # Optional: Extension icon

# Example: Python Extension
extension.mcpb (ZIP file)
├── manifest.json         # Required: Extension metadata and configuration
├── server/               # Server files
│   ├── main.py           # Main entry point
│   └── utils.py          # Additional modules
├── lib/                  # Bundled Python packages
├── requirements.txt      # Optional: Python dependencies list
└── icon.png              # Optional: Extension icon

The only required file in a Desktop Extension is a manifest.json. Claude Desktop handles all the complexity:

• Built-in runtime: Node.js ships with Claude Desktop, eliminating external dependencies
• Automatic updates: Extensions update automatically when new versions are available
• Secure secrets: Sensitive configuration like API keys are stored in the OS keychain

The manifest contains human-readable information (name, description, author), a declaration of features (tools, prompts), user configuration, and runtime requirements. Most fields are optional, so the minimal version is quite short, although in practice all three supported extension types (Node.js, Python, and classic binaries/executables) are expected to include files:

{
  "mcpb_version": "0.1",
  "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"
      ]
    }
  }
}

The specification includes convenience options that aim to make installation and configuration of local MCP servers easier. The server configuration object can be defined to accommodate both user-defined configuration via template literals and platform-specific overrides. Extension developers can define in detail what kind of configuration they want to collect from users.

Here is a concrete example of how the manifest aids with configuration. The developer declares that the user needs to supply an api_key. Claude will not enable the extension until the user supplies that value, keeps it automatically in the operating system's secret vault, and transparently replaces the ${user_config.api_key} with the user-supplied value when launching the server. Similarly, ${__dirname} gets replaced with the full path to the extension's unpacked directory.

{
  "mcpb_version": "0.1",
  "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"],
      "env": {
        "API_KEY": "${user_config.api_key}"
      }
    }
  },
  "user_config": {
    "api_key": {
      "type": "string",
      "title": "API Key",
      "description": "Your API key for authentication",
      "sensitive": true,
      "required": true
    }
  }
}

A full manifest.json with most optional fields might look like this:

{
  "mcpb_version": "0.1",
  "name": "My MCP Extension",
  "display_name": "My Awesome MCP Extension",
  "version": "1.0.0",
  "description": "A brief description of what this extension does",
  "long_description": "A detailed description that can include multiple paragraphs explaining the extension's functionality, use cases, and features. It supports basic markdown.",
  "author": {
    "name": "Your Name",
    "email": "yourname@example.com",
    "url": "https://your-website.com"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/your-username/my-mcp-extension"
  },
  "homepage": "https://example.com/my-extension",
  "documentation": "https://docs.example.com/my-extension",
  "support": "https://github.com/your-username/my-extension/issues",
  "icon": "icon.png",
  "screenshots": [
    "assets/screenshots/screenshot1.png",
    "assets/screenshots/screenshot2.png"
  ],
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"
      }
    }
  },
  "tools": [
    {
      "name": "search_files",
      "description": "Search for files in a directory"
    }
  ],
  "prompts": [
    {
      "name": "poetry",
      "description": "Have the LLM write poetry",
      "arguments": ["topic"],
      "text": "Write a creative poem about the following topic: ${arguments.topic}"
    }
  ],
  "tools_generated": true,
  "keywords": ["api", "automation", "productivity"],
  "license": "MIT",
  "compatibility": {
    "claude_desktop": ">=1.0.0",
    "platforms": ["darwin", "win32", "linux"],
    "runtimes": {
      "node": ">=16.0.0"
    }
  },
  "user_config": {
    "allowed_directories": {
      "type": "directory",
      "title": "Allowed Directories",
      "description": "Directories the server can access",
      "multiple": true,
      "required": true,
      "default": ["${HOME}/Desktop"]
    },
    "api_key": {
      "type": "string",
      "title": "API Key",
      "description": "Your API key for authentication",
      "sensitive": true,
      "required": false
    },
    "max_file_size": {
      "type": "number",
      "title": "Maximum File Size (MB)",
      "description": "Maximum file size to process",
      "default": 10,
      "min": 1,
      "max": 100
    }
  }
}

To see an extension and manifest, refer to the examples in the MCPB repository.

The full specification for all required and optional fields in the manifest.json can be found as part of the open-source toolchain.

Building your first extension

Walkthrough for packaging an existing MCP server as a Desktop Extension, using a simple file system server as an example.

Step 1: Create the manifest

Initialize a manifest for your server:

npx @anthropic-ai/mcpb init

This interactive tool asks about your server and generates a complete manifest.json. To speed-run the most basic manifest.json, run the command with a --yes parameter.

Step 2: Handle user configuration

If your server needs user input (like API keys or allowed directories), declare it in the manifest:

"user_config": {
  "allowed_directories": {
    "type": "directory",
    "title": "Allowed Directories",
    "description": "Directories the server can access",
    "multiple": true,
    "required": true,
    "default": ["${HOME}/Documents"]
  }
}

Claude Desktop will:

• Display a user-friendly configuration UI
• Validate inputs before enabling the extension
• Securely store sensitive values
• Pass configuration to your server either as arguments or environment variables, depending on developer configuration

Below is an example passing user configuration as an environment variable (though it could also be an argument):

"server": {
   "type": "node",
   "entry_point": "server/index.js",
   "mcp_config": {
   "command": "node",
   "args": ["${__dirname}/server/index.js"],
   "env": {
      "ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"
   }
   }
}

Step 3: Package the extension

Bundle everything into a .mcpb file:

npx @anthropic-ai/mcpb pack

This command:

1. Validates your manifest
2. Generates the .mcpb archive

Step 4: Test locally

Drag your .mcpb file into Claude Desktop's Settings window. You'll see:

• Human-readable information about your extension
• Required permissions and configuration
• A simple "Install" button

Advanced features

Cross-platform support

Extensions can adapt to different operating systems:

"server": {
  "type": "node",
  "entry_point": "server/index.js",
  "mcp_config": {
    "command": "node",
    "args": ["${__dirname}/server/index.js"],
    "platforms": {
      "win32": {
        "command": "node.exe",
        "env": {
          "TEMP_DIR": "${TEMP}"
        }
      },
      "darwin": {
        "env": {
          "TEMP_DIR": "${TMPDIR}"
        }
      }
    }
  }
}

Dynamic configuration

Use template literals for runtime values:

• ${__dirname}: Extension's installation directory
• ${user_config.key}: User-provided configuration
• ${HOME}, ${TEMP}: System environment variables

Feature declaration

Help users understand capabilities upfront:

"tools": [
  {
    "name": "read_file",
    "description": "Read contents of a file"
  }
],
"prompts": [
  {
    "name": "code_review",
    "description": "Review code for best practices",
    "arguments": ["file_path"]
  }
]

The extension directory

A curated directory of extensions launches built into Claude Desktop. Users can browse, search, and install with one click — no searching GitHub or vetting code.

Both the Desktop Extension specification and the implementation in Claude for macOS and Windows are expected to evolve over time.

To submit your extension:

1. Ensure it follows the guidelines found in the submission form
2. Test across Windows and macOS
3. Submit your extension
4. The Anthropic team reviews for quality and security

Building an open ecosystem

Anthropic states commitment to the open ecosystem around MCP servers and believes that its ability to be universally adopted by multiple applications and services has benefitted the community. In line with this commitment, they are open-sourcing the Desktop Extension specification, toolchain, and the schemas and key functions used by Claude for macOS and Windows to implement its own support of Desktop Extensions. The hope is that the MCPB format doesn't just make local MCP servers more portable for Claude, but other AI desktop applications, too.

What's being open-sourced:

• The complete MCPB specification
• Packaging and validation tools
• Reference implementation code
• TypeScript types and schemas

This means:

• For MCP server developers: Package once, run anywhere that supports MCPB
• For app developers: Add extension support without building from scratch
• For users: Consistent experience across all MCP-enabled applications

The specification and toolchain is intentionally versioned as 0.1, as Anthropic looks forward to working with the greater community on evolving and changing the format.

Security and enterprise considerations

Extensions introduce new security considerations, particularly for enterprises. Several safeguards are built in with the preview release:

For users

• Sensitive data stays in the OS keychain
• Automatic updates
• Ability to audit what extensions are installed

For enterprises

• Group Policy (Windows) and MDM (macOS) support
• Ability to pre-install approved extensions
• Blocklist specific extensions or publishers
• Disable the extension directory entirely
• Deploy private extension directories

For more information about managing extensions within an organization, see the Anthropic documentation.

Getting started

For MCP server developers: Review the developer documentation or run the following commands in a local MCP server's directory:

npm install -g @anthropic-ai/mcpb
mcpb init
mcpb pack

For Claude Desktop users: Update to the latest version and look for the Extensions section in Settings.

For enterprises: Review enterprise documentation for deployment options.

Building with Claude Code

Internally at Anthropic, Claude has proven great at building extensions with minimal intervention. For those wanting to use Claude Code, the recommendation is to briefly explain what the extension should do and add the following context to the prompt:

I want to build this as a Desktop Extension, abbreviated as "MCPB". Please follow these steps:

1. **Read the specifications thoroughly:**
   - https://github.com/anthropics/mcpb/blob/main/README.md - MCPB architecture overview, capabilities, and integration patterns
   - https://github.com/anthropics/mcpb/blob/main/MANIFEST.md - Complete extension manifest structure and field definitions
   - https://github.com/anthropics/mcpb/tree/main/examples - Reference implementations including a "Hello World" example

2. **Create a proper extension structure:**
   - Generate a valid manifest.json following the MANIFEST.md spec
   - Implement an MCP server using @modelcontextprotocol/sdk with proper tool definitions
   - Include proper error handling and timeout management

3. **Follow best development practices:**
   - Implement proper MCP protocol communication via stdio transport
   - Structure tools with clear schemas, validation, and consistent JSON responses
   - Make use of the fact that this extension will be running locally
   - Add appropriate logging and debugging capabilities
   - Include proper documentation and setup instructions

4. **Test considerations:**
   - Validate that all tool calls return properly structured responses
   - Verify manifest loads correctly and host integration works

Generate complete, production-ready code that can be immediately tested. Focus on defensive programming, clear error messages, and following the exact
MCPB specifications to ensure compatibility with the ecosystem.

Conclusion

Desktop Extensions represent a fundamental shift in how users interact with local AI tools. By removing installation friction, powerful MCP servers become accessible to everyone — not just developers.

Internally, Anthropic uses desktop extensions to share highly experimental MCP servers. One team experimented to see how far their models could make it when directly connected to a GameBoy, similar to their "Claude plays Pokemon" research. They used Desktop Extensions to package a single extension that opens up the popular PyBoy GameBoy emulator and lets Claude take control. Countless opportunities are believed to exist to connect the model's capabilities to the tools, data, and applications users already have on their local machines.

The same creativity that brought thousands of MCP servers can now reach millions of users with just one click.

Submit your extension for review

---

No author is explicitly listed on the article.