Desktop Extensions：为 Claude Desktop 提供一键式 MCP 服务器安装

# Claude Desktop Extensions: 一键安装 MCP server 到 Claude Desktop 来源：https://www.anthropic.com/engineering/desktop-extensions - 文件扩展名更新 2025年9月11日 Claude Desktop Extensions 现已使用 \.mcpb（MCP Bundle）文件扩展名，替代原有的 \.dxt。现有的 \.dxt 扩展仍可继续使用，但我们建议开发者在今后的新扩展中采用 \.mcpb。所有功能保持不变——这仅是命名规范的更新。 — 去年我们发布 Model Context Protocol（MCP）时，看到开发者们构建了出色的本地服务器，让 Claude 能够访问从文件系统到数据库的各种资源。但我们不断收到相同的反馈：安装过程太复杂。用户需要安装开发者工具，必须手动编辑配置文件，还经常被依赖问题卡住。 今天，我们推出 Desktop Extensions——一种全新的打包格式，让安装 MCP server 像点击按钮一样简单。 ### 解决 MCP 安装难题 本地 MCP server 为 Claude Desktop 用户解锁了强大的功能。它们可以与本地应用交互、访问私有数据、与开发工具集成——同时确保数据保留在用户的机器上。然而，当前的安装流程存在显著的门槛： - **需要开发者工具**：用户需要安装 Node.js、Python 或其他运行时环境 - **手动配置**：每个 server 都需要编辑 JSON 配置文件 - **依赖管理**：用户必须解决包冲突和版本不匹配问题 - **缺乏发现机制**：寻找有用的 MCP server 需要在 GitHub 上搜索 - **更新复杂**：保持 server 最新意味着手动重新安装 这些摩擦点意味着，尽管 MCP server 功能强大，但对非技术用户来说 largely 难以触及。 ### Desktop Extensions 简介 Desktop Extensions（`\.mcpb` 文件）通过将整个 MCP server（包括所有依赖）打包成单个可安装包来解决这些问题。以下是用户体验的变化： **以前：** `` # 先安装 Node.js npm install -g @example/mcp-server # 手动编辑 ~/.claude/claude_desktop_config.json # 重启 Claude Desktop # 希望它能正常工作 `` **现在：** 1. 下载一个 `\.mcpb` 文件 2. 双击用 Claude Desktop 打开 3. 点击"安装" 就这么简单。没有终端、没有配置文件、没有依赖冲突。 ## 架构概览 Desktop Extension 是一个 zip 压缩包，包含本地 MCP server 以及一个 `manifest\.json` 文件，后者描述了 Claude Desktop 及其他支持 desktop extensions 的应用所需了解的一切信息。 `` extension.mcpb (ZIP 压缩包) ├── manifest.json # 扩展元数据和配置 ├── server/ # MCP server 实现 │ └── [server 文件] ├── dependencies/ # 所有必需的包/库 └── icon.png # 可选：扩展图标 # 示例：Node.js Extension extension.mcpb ├── manifest.json # 必需：扩展元数据和配置 ├── server/ # Server 文件 │ └── index.js # 主入口点 ├── node_modules/ # 打包的依赖 ├── package.json # 可选：NPM 包定义 └── icon.png # 可选：扩展图标 # 示例：Python Extension extension.mcpb (ZIP 文件) ├── manifest.json # 必需：扩展元数据和配置 ├── server/ # Server 文件 │ ├── main.py # 主入口点 │ └── utils.py # 附加模块 ├── lib/ # 打包的 Python 包 ├── requirements.txt # 可选：Python 依赖列表 └── icon.png # 可选：扩展图标 `` Desktop Extension 中唯一必需的文件是 manifest.json。Claude Desktop 处理所有复杂性： - **内置运行时**：我们在 Claude Desktop 中内置了 Node.js，消除了外部依赖 - **自动更新**：有新版本时扩展自动更新 - **安全密钥**：API 密钥等敏感配置存储在 OS 钥匙串中 manifest 包含人类可读的信息（如名称、描述、作者）、功能声明（tools、prompts）、用户配置和运行时需求。大多数字段是可选的，因此最小版本非常简短，不过实践中，我们预计所有三种支持的扩展类型（Node.js、Python 和经典二进制/可执行文件）都会包含以下文件： `` { "mcpb_version": "0.1", // 此 manifest 遵循的 MCPB 规范版本 "name": "my-extension", // 机器可读名称（用于 CLI、API） "version": "1.0.0", // 扩展的语义化版本 "description": "A simple MCP extension", // 扩展功能的简要描述 "author": { // 作者信息（必需） "name": "Extension Author" // 作者名称（必需字段） }, "server": { // Server 配置（必需） "type": "node", // Server 类型："node"、"python" 或 "binary" "entry_point": "server/index.js", // 主 server 文件路径 "mcp_config": { // MCP server 配置 "command": "node", // 运行 server 的命令 "args": [ // 传递给命令的参数 "${__dirname}/server/index.js" // ${__dirname} 将被替换为扩展的目录 ] } } } `` manifest 规范中提供了许多便利选项（https://github.com/anthropics/dxt/blob/main/MANIFEST.md），旨在简化本地 MCP server 的安装和配置。server 配置对象可以以这种方式定义，既能容纳用户定义的模板字面量配置，也能支持平台特定的覆盖。扩展开发者可以详细定义希望从用户收集的配置类型。 让我们看一个具体的例子，了解 manifest 如何协助配置。在下面的 manifest 中，开发者声明用户需要提供一个 `api\_key`。Claude 在用户提供该值之前不会启用扩展，会自动将其保存在操作系统的秘密保险库中，并在启动 server 时透明地将 `${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": "[email protected]", "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 } } } `` 要查看扩展和 manifest 示例，请参考 MCPB 仓库中的示例（https://github.com/anthropics/dxt/tree/main/examples）。 `manifest\.json` 中所有必需和可选字段的完整规范可以在我们的开源工具链中找到（https://github.com/anthropics/dxt/blob/main/MANIFEST.md）。 ### 构建你的第一个扩展 让我们逐步介绍如何将现有的 MCP server 打包为 Desktop Extension。我们将以简单的文件系统 server 为例。 #### 第 1 步：创建 manifest 首先，为你的 server 初始化一个 manifest： `` npx @anthropic-ai/mcpb init `` 这个交互式工具会询问关于你的 server 的信息，并生成完整的 manifest.json。如果你想快速生成最基本的 manifest.json，可以使用 --yes 参数运行该命令。 #### 第 2 步：处理用户配置 如果你的 server 需要用户输入（如 API 密钥或允许的目录），在 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 将会： - 显示用户友好的配置界面 - 在启用扩展前验证输入 - 安全存储敏感值 - 根据开发者配置，将配置作为参数或环境变量传递给你的 server 在下面的示例中，我们将用户配置作为环境变量传递，但它也可以是参数。 `` "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 `` 此命令将： 1. 验证你的 manifest 2. 生成 `\.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 的能力。 提交你的扩展： 1. 确保遵循提交表单中的指南 2. 在 Windows 和 macOS 上进行测试 3. 提交你的扩展（https://docs.google.com/forms/d/14_Dmcig4z8NeRMB_e7TOyrKzuZ88-BLYdLvS6LPhiZU/edit） 4. 我们的团队将审核质量和安全性 ### 构建开放生态 我们致力于围绕 MCP server 构建开放生态，并相信其被多个应用和服务普遍采用的能力已经造福了社区。秉承这一承诺，我们将 Desktop Extension 规范、工具链以及 Claude for macOS 和 Windows 用于实现 Desktop Extensions 支持的模式和关键函数开源。我们希望 MCPB 格式不仅能让本地 MCP server 对 Claude 更具可移植性，也能惠及其他 AI 桌面应用。 我们将开源： - 完整的 MCPB 规范 - 打包和验证工具 - 参考实现代码 - TypeScript 类型和模式 这意味着： - **对 MCP server 开发者**：一次打包，在任何支持 MCPB 的地方运行 - **对应用开发者**：无需从零开始即可添加扩展支持 - **对用户**：在所有支持 MCP 的应用中获得一致体验 规范和工具链特意标记为 0.1 版本，因为我们期待与更广泛的社区合作演进和改变该格式。我们期待听到你的反馈。 ### 安全与企业考量 我们理解扩展引入了新的安全考量，尤其是对企业而言。我们在 Desktop Extensions 预览版中内置了多项安全保障： #### 对用户 - 敏感数据保留在 OS 钥匙串中 - 自动更新 - 能够审计已安装的扩展 #### 对企业 - 支持组策略（Windows）和 MDM（macOS） - 能够预装已批准的扩展 - 屏蔽特定扩展或发布者 - 完全禁用扩展目录 - 部署私有扩展目录 有关如何在组织内管理扩展的更多信息，请参阅我们的文档（https://support.anthropic.com/en/articles/10949351-getting-started-with-model-context-protocol-mcp-on-claude-for-desktop）。 ### 开始使用 准备好构建你自己的扩展了吗？以下是