文件扩展名更新
2025 年 9 月 11 日
Claude Desktop 扩展现在使用 .mcpb（MCP Bundle）文件扩展名，取代原来的 .dxt。现有的 .dxt 扩展仍可继续使用，但我们建议开发者今后为新扩展使用 .mcpb。所有功能保持不变——这纯粹是命名约定的更新。
—
去年我们发布 Model Context Protocol（MCP）时，看到开发者构建了许多出色的本地服务器，让 Claude 能够访问从文件系统到数据库的各种资源。但我们不断听到同样的反馈：安装太复杂了。用户需要开发者工具，要手动编辑配置文件，还常常卡在依赖问题上。
今天，我们推出 Desktop Extensions——一种全新的打包格式，让安装 MCP 服务器像点击按钮一样简单。
解决 MCP 安装难题
本地 MCP 服务器为 Claude Desktop 用户解锁了强大的能力。它们可以与本地应用交互、访问私有数据、集成开发工具，同时让数据始终留在用户的机器上。然而，目前的安装流程造成了很大的障碍：
- 需要开发者工具：用户需要安装 Node.js、Python 或其他运行时
- 手动配置：每个服务器都需要编辑 JSON 配置文件
- 依赖管理：用户必须自行解决包冲突和版本不匹配问题
- 缺乏发现机制：寻找好用的 MCP 服务器需要去 GitHub 上搜索
- 更新繁琐：保持服务器为最新版本意味着手动重新安装
这些摩擦点意味着，MCP 服务器尽管功能强大，对非技术用户而言仍然基本难以使用。
Desktop Extensions 简介
Desktop Extensions（.mcpb 文件）把整个 MCP 服务器连同所有依赖打包进一个可安装的包中，从而解决这些问题。对用户而言，变化如下：
之前：
# Install Node.js first
npm install -g @example/mcp-server
# Edit ~/.claude/claude_desktop_config.json manually
# Restart Claude Desktop
# Hope it works
之后：
- 下载一个
.mcpb文件 - 双击，用 Claude Desktop 打开
- 点击“安装”
就是这样。不用终端，不用配置文件，没有依赖冲突。
架构概览
Desktop Extension 是一个 zip 压缩包，其中包含本地 MCP 服务器以及一个 manifest.json，后者描述了 Claude Desktop 和其他支持桌面扩展的应用需要了解的全部信息。
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
Desktop Extension 中唯一必需的文件是 manifest.json。Claude Desktop 会处理所有复杂的事情：
- 内置运行时：我们随 Claude Desktop 一起提供 Node.js，消除了对外部依赖的需求
- 自动更新：有新版本时，扩展会自动更新
- 安全存储密钥：API 密钥等敏感配置存储在操作系统的钥匙串中
清单（manifest）包含人类可读的信息（如名称、描述或作者）、功能声明（工具、提示词）、用户配置以及运行时要求。大多数字段是可选的，因此最精简的版本相当短，不过在实践中，我们预计三种受支持的扩展类型（Node.js、Python 和传统二进制/可执行文件）都会包含以下文件：
{
"mcpb_version": "0.1", // MCPB spec version this manifest conforms to
"name": "my-extension", // Machine-readable name (used for CLI, APIs)
"version": "1.0.0", // Semantic version of your extension
"description": "A simple MCP extension", // Brief description of what the extension does
"author": { // Author information (required)
"name": "Extension Author" // Author's name (required field)
},
"server": { // Server configuration (required)
"type": "node", // Server type: "node", "python", or "binary"
"entry_point": "server/index.js", // Path to the main server file
"mcp_config": { // MCP server configuration
"command": "node", // Command to run the server
"args": [ // Arguments passed to the command
"${__dirname}/server/index.js" // ${__dirname} is replaced with the extension's directory
]
}
}
}
清单规范中提供了许多便捷选项，旨在让本地 MCP 服务器的安装和配置更加容易。服务器配置对象的定义方式，既为模板字面量形式的用户自定义配置留出空间，也支持特定平台的覆盖设置。扩展开发者可以详细定义希望向用户收集哪些配置。
我们来看一个具体例子，了解清单如何辅助配置。在下面的清单中，开发者声明用户需要提供一个 api_key。在用户提供该值之前，Claude 不会启用这个扩展；它会自动把该值保存在操作系统的密钥库中，并在启动服务器时，用户提供的值透明地替换 ${user_config.api_key}。同样，${__dirname} 会被替换为扩展解压目录的完整路径。
{
"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
}
}
}
一个包含大部分可选字段的完整 manifest.json 可能如下所示：
{
"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
}
}
}
要查看扩展和清单的示例，请参阅MCPB 代码仓库中的示例。
manifest.json 中所有必填和可选字段的完整规范，可在我们的开源工具链中找到。
构建你的第一个扩展
我们来演示如何把一个现有的 MCP 服务器打包成 Desktop Extension，这里以一个简单的文件系统服务器为例。
第 1 步：创建清单
首先，为你的服务器初始化一个清单：
npx @anthropic-ai/mcpb init
这个交互式工具会询问你的服务器信息，并生成完整的 manifest.json。如果你想以最快速度得到最基础的 manifest.json，可以在命令中加上 --yes 参数。
第 2 步：处理用户配置
如果你的服务器需要用户输入（如 API 密钥或允许访问的目录），请在清单中声明：
"user_config": {
"allowed_directories": {
"type": "directory",
"title": "Allowed Directories",
"description": "Directories the server can access",
"multiple": true,
"required": true,
"default": ["${HOME}/Documents"]
}
}
Claude Desktop 将会：
- 显示用户友好的配置界面
- 在启用扩展之前验证输入
- 安全地存储敏感值
- 根据开发者的配置，以参数或环境变量的形式把配置传递给你的服务器
在下面的示例中，我们把用户配置作为环境变量传递，但也可以作为参数传递。
"server": {
"type": "node",
"entry_point": "server/index.js",
"mcp_config": {
"command": "node",
"args": ["${__dirname}/server/index.js"],
"env": {
"ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"
}
}
}
第 3 步：打包扩展
把所有内容打包成一个 .mcpb 文件：
npx @anthropic-ai/mcpb pack
该命令会：
- 验证你的清单
- 生成
.mcpb压缩包
第 4 步：本地测试
把你的 .mcpb 文件拖进 Claude Desktop 的“设置”窗口。你会看到：
- 关于你的扩展的人类可读信息
- 所需的权限和配置
- 一个简单的“安装”按钮
高级功能
跨平台支持
扩展可以适配不同的操作系统：
"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}"
}
}
}
}
}
动态配置
使用模板字面量表示运行时的值：
${__dirname}：扩展的安装目录${user_config.key}：用户提供的配置${HOME}, ${TEMP}：系统环境变量
功能声明
让用户提前了解扩展的能力：
"tools": [
{
"name": "read_file",
"description": "Read contents of a file"
}
],
"prompts": [
{
"name": "code_review",
"description": "Review code for best practices",
"arguments": ["file_path"]
}
]
扩展目录
我们上线时提供一个内置于 Claude Desktop 的精选扩展目录。用户可以一键浏览、搜索和安装——无需在 GitHub 上搜索，也无需自己审查代码。
我们预计 Desktop Extension 规范以及 Claude for macOS 和 Windows 中的实现都会随时间演进，同时期待看到人们以各种创造性的方式利用扩展来拓展 Claude 的能力。
提交你的扩展：
- 确保它遵循提交表单中的指南
- 在 Windows 和 macOS 上测试
- 提交你的扩展
- 我们的团队会审查质量和安全性
构建开放的生态系统
我们致力于围绕 MCP 服务器构建开放的生态系统，并相信它能被多个应用和服务普遍采用，这一点已让社区受益。基于这一承诺，我们将开源 Desktop Extension 规范、工具链，以及 Claude for macOS 和 Windows 用来实现自身 Desktop Extensions 支持的 schema 和关键函数。我们希望 MCPB 格式不仅能让本地 MCP 服务器在 Claude 中更易移植，也能让其他 AI 桌面应用受益。
我们开源的内容包括：
- 完整的 MCPB 规范
- 打包和验证工具
- 参考实现代码
- TypeScript 类型和 schema
这意味着：
- 对 MCP 服务器开发者：一次打包，在任何支持 MCPB 的地方运行
- 对应用开发者：无需从零开始构建，即可添加扩展支持
- 对用户：在所有支持 MCP 的应用中获得一致的体验
规范和工具链有意标注为 0.1 版本，因为我们期待与更广泛的社区合作，共同演进和改进这一格式。期待听到你的反馈。
安全与企业考量
我们理解，扩展会带来新的安全考量，对企业尤其如此。在 Desktop Extensions 的预览版中，我们内置了若干安全措施：
对用户
- 敏感数据保存在操作系统钥匙串中
- 自动更新
- 可审计已安装的扩展
对企业
- 支持组策略（Windows）和 MDM（macOS）
- 可预先安装已批准的扩展
- 可将特定扩展或发布者加入黑名单
- 可完全禁用扩展目录
- 可部署私有扩展目录
有关如何在组织内管理扩展的更多信息，请参阅我们的文档。
开始使用
准备好构建你自己的扩展了吗？从这里开始：
对 MCP 服务器开发者：查阅我们的开发者文档，或者直接在本地 MCP 服务器的目录中运行以下命令：
npm install -g @anthropic-ai/mcpb
mcpb init
mcpb pack
对 Claude Desktop 用户：更新到最新版本，并在“设置”中找到“扩展”部分
对企业：查阅我们的企业文档，了解部署选项
借助 Claude Code 构建
在 Anthropic 内部，我们发现 Claude 只需极少干预就能很好地构建扩展。如果你也想使用 Claude Code，建议你先简要说明希望扩展做什么，然后在提示词中加入以下上下文：
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.
结语
Desktop Extensions 代表了用户与本地 AI 工具交互方式的根本转变。通过消除安装的摩擦，我们让强大的 MCP 服务器不再只属于开发者，而是人人可用。
在内部，我们用 Desktop Extensions 来分享一些高度实验性的 MCP 服务器——有的好玩，有的实用。有一个团队试验了让我们的模型直接连接 GameBoy 能走多远，类似我们的“Claude 玩宝可梦”研究。我们用 Desktop Extensions 打包了一个扩展，它能打开流行的 PyBoy GameBoy 模拟器，并让 Claude 接管控制。我们相信，把模型的能力连接到用户本地机器上已有的工具、数据和应用，蕴藏着无数机会。
我们迫不及待想看到你的作品。曾带来数千个 MCP 服务器的那份创造力，如今只需一次点击就能触达数百万用户。准备好分享你的 MCP 服务器了吗？提交你的扩展以供审核。
