获取开发者新闻通讯
产品更新、操作指南、社区聚焦等。每月发送至您的收件箱。
文件扩展名更新
2025年9月11日
Claude Desktop 扩展现在使用 .mcpb（MCP Bundle）文件扩展名，而非 .dxt。现有的 .dxt 扩展将继续正常工作，但我们建议开发者今后为新扩展使用 .mcpb。所有功能保持不变——这纯粹是命名约定的更新。
—
去年我们发布模型上下文协议（MCP）时，我们看到开发者构建了令人惊叹的本地服务器，让 Claude 能够访问从文件系统到数据库的一切。但我们不断听到同样的反馈：安装过于复杂。用户需要开发者工具，必须手动编辑配置文件，还经常卡在依赖问题上。
今天，我们推出桌面扩展——一种新的打包格式，让安装 MCP 服务器变得像点击按钮一样简单。
本地 MCP 服务器为 Claude Desktop 用户解锁了强大的能力。它们可以与本地应用程序交互、访问私有数据，并与开发工具集成——同时将所有数据保留在用户自己的机器上。然而，当前的安装流程造成了显著的障碍：
这些摩擦点意味着，MCP 服务器尽管功能强大，但对非技术用户而言基本上仍然无法使用。
桌面扩展（.mcpb
文件）通过将整个 MCP 服务器——包括所有依赖项——打包成一个可安装的单一包，解决了这些问题。以下是用户端的变化：
之前：
# 先安装 Node.js
npm install -g @example/mcp-server
# 手动编辑 ~/.claude/claude_desktop_config.json
# 重启 Claude Desktop
# 希望它能正常工作
之后：
.mcpb
文件。就这样。没有终端，没有配置文件，没有依赖冲突。
桌面扩展是一个 zip 压缩包，其中包含本地 MCP 服务器以及一个 manifest.json
，它描述了 Claude Desktop 和其他支持桌面扩展的应用所需了解的一切。
extension.mcpb（ZIP 归档文件）
├── manifest.json # 扩展元数据与配置
├── server/ # MCP 服务器实现
│ └── [服务器文件]
├── dependencies/ # 所有必需的包/库
└── icon.png # 可选：扩展图标
# 示例：Node.js 扩展
extension.mcpb
├── manifest.json # 必需：扩展元数据与配置
├── server/ # 服务器文件
│ └── index.js # 主入口点
├── node_modules/ # 打包的依赖项
├── package.json # 可选：NPM 包定义
└── icon.png # 可选：扩展图标
# 示例：Python 扩展
extension.mcpb（ZIP 文件）
├── manifest.json # 必需：扩展元数据与配置
├── server/ # 服务器文件
│ ├── main.py # 主入口点
│ └── utils.py # 附加模块
├── lib/ # 打包的 Python 包
├── requirements.txt # 可选：Python 依赖列表
└── icon.png # 可选：扩展图标
桌面扩展中唯一必需的文件是 manifest.json。Claude Desktop 处理所有复杂性：
清单包含人类可读的信息（如名称、描述或作者）、功能声明（工具、提示）、用户配置以及运行时要求。大多数字段都是可选的，因此最小版本相当简短，尽管在实践中，我们预期所有三种受支持的扩展类型（Node.js、Python 以及经典二进制文件/可执行文件）都会包含文件：
{
"mcpb_version": "0.1", // 此清单所遵循的 MCPB 规范版本
"name": "my-extension", // 机器可读的名称（用于 CLI、API）
"version": "1.0.0", // 你的扩展的语义化版本
"description": "A simple MCP extension", // 扩展功能的简要描述
"author": { // 作者信息（必填）
"name": "Extension Author" // 作者姓名（必填字段）
},
"server": { // 服务器配置（必填）
"type": "node", // 服务器类型："node"、"python" 或 "binary"
"entry_point": "server/index.js", // 主服务器文件的路径
"mcp_config": { // MCP 服务器配置
"command": "node", // 用于运行服务器的命令
"args": [ // 传递给命令的参数
"${__dirname}/server/index.js" // ${__dirname} 会被替换为扩展所在的目录
]
}
}
}
在清单规范中有许多便捷选项，旨在让本地 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 服务器打包为桌面扩展。我们将以一个简单的文件系统服务器为例。
首先，为你的服务器初始化一个清单：
npx @anthropic-ai/mcpb init
这个交互式工具会询问你的服务器相关信息，并生成一个完整的 manifest.json。如果你想快速生成最基本的 manifest.json，可以运行带有 --yes 参数的命令。
如果你的服务器需要用户输入（如 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}"
}
}
}
将所有内容打包成一个 .mcpb
文件：
npx @anthropic-ai/mcpb pack
此命令：
.mcpb
归档将你的 .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 上搜索或审查代码。
虽然我们预计桌面扩展规范和 Claude for macOS 和 Windows 中的实现会随着时间的推移而演变，但我们期待看到扩展能以多种方式创造性地扩展 Claude 的能力。
要提交您的扩展：
我们致力于围绕 MCP 服务器的开放生态系统，并相信其被多个应用程序和服务普遍采用的能力使社区受益。根据这一承诺，我们开源了桌面扩展规范、工具链以及 Claude for macOS 和 Windows 用于实现自身对桌面扩展支持的架构和关键功能。我们希望 MCPB 格式不仅能让本地 MCP 服务器对 Claude 更具可移植性，也能对其他 AI 桌面应用程序如此。
我们正在开源：
这意味着：
规范和工具链特意版本化为 0.1，因为我们期待与更广泛的社区合作，共同演进和改变格式。我们期待您的反馈。
我们理解扩展引入了新的安全考虑，特别是对企业而言。在桌面扩展的预览版中，我们内置了几项保护措施：
有关如何在您的组织内管理扩展的更多信息，请参阅我们的文档。
准备好构建自己的扩展了吗？以下是开始的方法：
对于 MCP 服务器开发者：查看我们的开发者文档 – 或者直接在本地 MCP 服务器目录中运行以下命令：
npm install -g @anthropic-ai/mcpb
mcpb init
mcpb pack
对于 Claude Desktop 用户：更新到最新版本，并在设置中查找“扩展”部分
对于企业：查看我们的企业文档以了解部署选项
在 Anthropic 内部，我们发现 Claude 非常擅长以最少的干预构建扩展。如果你也想使用 Claude Code，我们建议你简要说明你希望扩展做什么，然后在提示中添加以下上下文：
我想将其构建为桌面扩展（Desktop Extension），缩写为“MCPB”。请遵循以下步骤：
1. **彻底阅读规范：**
- https://github.com/anthropics/mcpb/blob/main/README.md - MCPB 架构概述、能力与集成模式
- https://github.com/anthropics/mcpb/blob/main/MANIFEST.md - 完整的扩展清单结构与字段定义
- https://github.com/anthropics/mcpb/tree/main/examples - 参考实现，包括一个“Hello World”示例
2. **创建正确的扩展结构：**
- 按照 MANIFEST.md 规范生成有效的 manifest.json
- 使用 @modelcontextprotocol/sdk 实现 MCP 服务器，并包含正确的工具定义
- 包含适当的错误处理与超时管理
3. **遵循最佳开发实践：**
- 通过 stdio 传输实现正确的 MCP 协议通信
- 以清晰的模式、验证和一致的 JSON 响应来组织工具
- 利用该扩展将在本地运行这一事实
- 添加适当的日志记录与调试能力
- 包含适当的文档与设置说明
4. **测试注意事项：**
- 验证所有工具调用都返回结构正确的响应
- 验证清单正确加载且宿主集成正常工作
生成完整、可立即测试的生产级代码。专注于防御性编程、清晰的错误消息，并遵循确切的
MCPB 规范，以确保与生态系统的兼容性。
桌面扩展代表了用户与本地 AI 工具交互方式的根本性转变。通过消除安装障碍，我们让强大的 MCP 服务器对所有人——而不仅仅是开发者——触手可及。
在内部，我们使用桌面扩展来分享高度实验性的 MCP 服务器——有些有趣，有些实用。一个团队进行了实验，看看当我们的模型直接连接到 GameBoy 时能走多远，类似于我们的“Claude 玩宝可梦”研究。我们使用桌面扩展打包了一个单一的扩展，它打开了流行的 PyBoy GameBoy 模拟器，并让 Claude 进行控制。我们相信，将模型的能力与用户本地机器上已有的工具、数据和应用程序连接起来，存在着无数的机会。
我们迫不及待地想看到你构建的东西。曾经为我们带来数千个 MCP 服务器的创造力，现在只需点击一下就能触达数百万用户。准备好分享你的 MCP 服务器了吗？提交你的扩展以供审核。
产品更新、操作指南、社区聚焦等。每月发送到你的收件箱。