桌面扩展：一键安装 Claude 桌面版 MCP 服务器
翻译自官网：Claude Desktop Extensions: One-click MCP server installation for Claude Desktop Anthropic
桌面扩展：一键安装 Claude 桌面版 MCP 服务器
发布于 2025 年 6 月 26 日
桌面扩展让安装 MCP 服务器变得像点击按钮一样简单。我们将分享技术架构以及创建优质扩展的技巧。
去年我们发布模型上下文协议（MCP）时，看到开发者们构建了出色的本地服务器，让 Claude 能够访问从文件系统到数据库的各种资源。但我们不断收到相同的反馈：安装过程太复杂。用户需要开发者工具，必须手动编辑配置文件，还经常陷入依赖问题的困境。
今天，我们推出桌面扩展 —— 一种新的打包格式，让安装 MCP 服务器变得像点击按钮一样简单。
解决 MCP 安装问题
本地 MCP 服务器为 Claude 桌面版用户解锁了强大功能。他们可以与本地应用程序交互、访问私人数据、集成开发工具 —— 所有这些都能确保数据保存在用户的设备上。然而，当前的安装过程存在诸多障碍：
- 需要开发者工具：用户需要安装 Node.js、Python 或其他运行时环境
- 手动配置：每个服务器都需要编辑 JSON 配置文件
- 依赖管理：用户必须解决包冲突和版本不匹配问题
- 没有发现机制：寻找有用的 MCP 服务器需要搜索 GitHub
- 更新复杂：保持服务器为最新版本意味着要手动重新安装
这些麻烦之处使得 MCP 服务器尽管功能强大，却在很大程度上让非技术用户难以使用。
推出桌面扩展
桌面扩展（.dxt 文件）通过将整个 MCP 服务器（包括所有依赖项）捆绑到一个可安装的包中，解决了这些问题。以下是用户将感受到的变化：
之前：
plaintext
# 首先安装 Node.js
npm install -g @example/mcp-server
# 手动编辑 ~/.claude/claude_desktop_config.json
# 重启 Claude 桌面版
# 祈祷能正常工作
之后：
- 下载 .dxt 文件
- 双击用 Claude 桌面版打开
- 点击 “安装”
就是这样。无需终端，无需配置文件，没有依赖冲突。
架构概述
桌面扩展是一个 zip 压缩包，包含本地 MCP 服务器以及 manifest.json，该文件描述了 Claude 桌面版和其他支持桌面扩展的应用程序需要了解的所有信息。
plaintext
extension.dxt（ZIP 压缩包）
├── manifest.json # 扩展元数据和配置
├── server/ # MCP 服务器实现
│ └── [服务器文件]
├── dependencies/ # 所有必需的包/库
└── icon.png # 可选：扩展图标
# 示例：Node.js 扩展
extension.dxt
├── manifest.json # 必需：扩展元数据和配置
├── server/ # 服务器文件
│ └── index.js # 主入口点
├── node_modules/ # 捆绑的依赖项
├── package.json # 可选：NPM 包定义
└── icon.png # 可选：扩展图标
# 示例：Python 扩展
extension.dxt（ZIP 文件）
├── manifest.json # 必需：扩展元数据和配置
├── server/ # 服务器文件
│ ├── main.py # 主入口点
│ └── utils.py # 其他模块
├── lib/ # 捆绑的 Python 包
├── requirements.txt # 可选：Python 依赖项列表
└── icon.png # 可选：扩展图标
桌面扩展中唯一必需的文件是 manifest.json。Claude 桌面版会处理所有复杂工作：
- 内置运行时：我们在 Claude 桌面版中内置了 Node.js，消除了外部依赖
- 自动更新：当有新版本可用时，扩展会自动更新
- 安全的密钥：像 API 密钥这样的敏感配置存储在操作系统的密钥链中
清单包含人类可读的信息（如名称、描述或作者）、功能声明（工具、提示）、用户配置和运行时要求。大多数字段是可选的，所以最小版本非常简短，不过实际上，我们期望所有三种受支持的扩展类型（Node.js、Python 和经典二进制文件 / 可执行文件）都包含相应文件：
json
{
"dxt_version": "0.1", // 此清单遵循的 DXT 规范版本
"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 在用户提供该值之前不会启用扩展，会自动将其保存在操作系统的密钥库中，并在启动服务器时将 透明地替换为用户提供的值。同样，{__dirname} 会替换为扩展解包目录的完整路径。
json
{
"dxt_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 可能如下所示：
json
{
"dxt_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
}
}
}
要查看扩展和清单，请参考 dxt 存储库中的示例。
manifest.json 中所有必需和可选字段的完整规范可在我们的开源工具链中找到。
构建你的第一个扩展
让我们逐步将现有的 MCP 服务器打包为桌面扩展。我们将以一个简单的文件系统服务器为例。
步骤 1：创建清单
首先，为你的服务器初始化一个清单：
plaintext
npx @anthropic-ai/dxt init
这个交互式工具会询问关于你的服务器的信息，并生成一个完整的 manifest.json。如果你想快速生成最基本的 manifest.json，可以在运行命令时加上 --yes 参数。
步骤 2：处理用户配置
如果你的服务器需要用户输入（如 API 密钥或允许的目录），在清单中声明：
json
"user_config": {
"allowed_directories": {
"type": "directory",
"title": "Allowed Directories",
"description": "Directories the server can access",
"multiple": true,
"required": true,
"default": ["${HOME}/Documents"]
}
}
Claude 桌面版会：
- 显示用户友好的配置界面
- 在启用扩展前验证输入
- 安全存储敏感值
- 根据开发者配置，将配置作为参数或环境变量传递给服务器
在下面的示例中，我们将用户配置作为环境变量传递，不过它也可以作为参数传递。
json
"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：打包扩展
将所有内容捆绑到 .dxt 文件中：
plaintext
npx @anthropic-ai/dxt pack
这个命令会：
- 验证你的清单
- 生成 .dxt 压缩包
步骤 4：本地测试
将你的 .dxt 文件拖到 Claude 桌面版的设置窗口中。你会看到：
- 关于你的扩展的人类可读信息
- 必需的权限和配置
- 一个简单的 “安装” 按钮
高级功能
跨平台支持
扩展可以适应不同的操作系统：
json
"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}：用户提供的配置
- 、{TEMP}：系统环境变量
功能声明
帮助用户预先了解功能：
json
"tools": [
{
"name": "read_file",
"description": "Read contents of a file"
}
],
"prompts": [
{
"name": "code_review",
"description": "Review code for best practices",
"arguments": ["file_path"]
}
]
扩展目录
我们推出时，Claude 桌面版中内置了一个精选的扩展目录。用户可以浏览、搜索并一键安装 —— 无需搜索 GitHub 或审查代码。
虽然我们预计桌面扩展规范以及在 macOS 和 Windows 版 Claude 中的实现会随着时间的推移而发展，但我们期待看到扩展以创造性的方式扩展 Claude 功能的各种方式。
提交你的扩展：
- 确保它符合提交表单中的指南
- 在 Windows 和 macOS 上进行测试
- 提交你的扩展
- 我们的团队会进行质量和安全性审查
构建开放生态系统
我们致力于围绕 MCP 服务器构建开放生态系统，并相信它被多个应用程序和服务普遍采用的能力已经使社区受益。根据这一承诺，我们正在开源桌面扩展规范、工具链以及 Claude 在 macOS 和 Windows 上用于实现自身对桌面扩展支持的模式和关键功能。我们希望 dxt 格式不仅能让 Claude 的本地 MCP 服务器更易于移植，也能让其他 AI 桌面应用程序受益。
我们正在开源：
- 完整的 DXT 规范
- 打包和验证工具
- 参考实现代码
- TypeScript 类型和模式
这意味着：
- 对于 MCP 服务器开发者：一次打包，在所有支持 DXT 的地方运行
- 对于应用开发者：无需从零开始构建即可添加扩展支持
- 对于用户：在所有支持 MCP 的应用程序中获得一致的体验
该规范和工具链特意版本化为 0.1，因为我们期待与更广泛的社区合作来发展和改变这种格式。我们期待收到你的反馈。
安全性和企业考虑因素
我们理解扩展带来了新的安全考虑，特别是对于企业而言。在桌面扩展的预览版本中，我们内置了几项安全措施：
对于用户
- 敏感数据保存在操作系统密钥链中
- 自动更新
- 能够审计已安装的扩展
对于企业
- 支持组策略（Windows）和 MDM（macOS）
- 能够预安装已批准的扩展
- 可将特定扩展或发布者列入黑名单
- 完全禁用扩展目录
- 部署私人扩展目录
有关如何在你的组织内管理扩展的更多信息，请参阅我们的文档。
入门指南
准备好构建你自己的扩展了吗？以下是开始的方法：
对于 MCP 服务器开发者：查看我们的开发者文档 —— 或者直接在你的本地 MCP 服务器目录中运行以下命令：
plaintext
npm install -g @anthropic-ai/dxt
dxt init
dxt pack
对于 Claude 桌面版用户：更新到最新版本，在设置中查找 “扩展” 部分
对于企业：查看我们的企业文档了解部署选项
使用 Claude Code 进行开发
在 Anthropic 内部，我们发现 Claude 在开发扩展方面表现出色，几乎不需要额外干预。如果您也想使用 Claude Code，我们建议您简要说明希望扩展实现的功能，然后在提示中添加以下内容：
我想将其构建为桌面扩展（Desktop Extension），简称为 “DXT”。请遵循以下步骤：
-
彻底阅读规范：
- https://github.com/anthropics/dxt/blob/main/README.md —— DXT 架构概述、功能及集成模式
- https://github.com/anthropics/dxt/blob/main/MANIFEST.md —— 完整的扩展清单结构和字段定义
- https://github.com/anthropics/dxt/tree/main/examples —— 参考实现，包括 “Hello World” 示例
-
创建合适的扩展结构：
- 按照 MANIFEST.md 规范生成有效的 manifest.json
- 使用 @modelcontextprotocol/sdk 实现 MCP 服务器，并包含适当的工具定义
- 加入适当的错误处理和超时管理机制
-
遵循最佳开发实践：
- 通过标准输入输出（stdio）传输实现规范的 MCP 协议通信
- 工具结构需包含清晰的模式、验证机制和一致的 JSON 响应
- 充分利用该扩展将在本地运行这一特性
- 添加适当的日志记录和调试功能
- 包含完善的文档和设置说明
-
测试注意事项：
- 验证所有工具调用均返回结构规范的响应
- 确认清单加载正常且与宿主应用的集成能够正常工作
生成完整的、可用于生产环境的代码，且该代码可立即进行测试。重点关注防御性编程、清晰的错误信息，并严格遵循 DXT 规范，以确保与生态系统的兼容性。
结语
桌面扩展从根本上改变了用户与本地 AI 工具的交互方式。通过消除安装障碍，我们让强大的 MCP 服务器变得人人可用 —— 而不仅仅是开发者。
在内部，我们正利用桌面扩展来分享高度实验性的 MCP 服务器 —— 有些很有趣，有些很实用。有个团队做了一项实验，探究当我们的模型直接连接到 GameBoy 时能实现多大程度的交互，这与我们 “Claude 玩 Pokémon” 的研究类似。我们通过桌面扩展打包了一个程序，它能打开广受欢迎的 PyBoy GameBoy 模拟器，并让 Claude 获得控制权。我们相信，将模型的能力与用户本地设备上已有的工具、数据和应用程序相连，存在着无数的可能性。
我们迫不及待想看到您开发的成果。曾经催生出数千个 MCP 服务器的创造力，如今只需一键就能触达数百万用户。准备好分享您的 MCP 服务器了吗？提交您的扩展进行审核吧。
写在最后
Claude code 目前在国内被墙，而且难以购买，费用昂贵，使用时还得担心被封号的风险，令人担心。
我推荐一个很好用的镜像站：
www.aicodemirror.com
不仅可以永久免费试用，价格也是非常公道，比官方便宜很多。填写邀请码 5OTTEB还可以额外获得50美金额度，快一起白嫖！
