Desktop Extensions：Claude Desktop 的一键 MCP 服务器安装

发布日期： 2025年6月26日

更新（2025年9月11日）： Claude Desktop Extensions 现在使用 .mcpb（MCP Bundle）文件扩展名代替 .dxt。现有的 .dxt 扩展继续有效，但建议开发者在新扩展中使用 .mcpb。所有功能保持不变——这纯粹是命名约定的更新。

Desktop Extensions 让安装 MCP 服务器变得像点击按钮一样简单。本文分享了技术架构和创建优质扩展的技巧。

解决 MCP 安装难题

本地 MCP 服务器为 Claude Desktop 用户解锁了强大功能。它们可以与本地应用程序交互、访问私有数据、并与开发工具集成——所有数据都保留在用户的机器上。然而，当前的安装过程存在显著障碍：

需要开发者工具： 用户需要安装 Node.js、Python 或其他运行时
手动配置： 每个服务器都需要编辑 JSON 配置文件
依赖管理： 用户必须解决包冲突和版本不匹配问题
没有发现机制： 发现有用的 MCP 服务器需要搜索 GitHub
更新复杂： 保持服务器最新意味着手动重新安装

这些摩擦点意味着 MCP 服务器尽管功能强大，但对非技术用户来说基本上无法使用。

介绍 Desktop Extensions

Desktop Extensions（.mcpb 文件）通过将整个 MCP 服务器（包括所有依赖）打包成单个可安装包来解决这些问题。以下是用户体验的变化：

之前：

# 首先安装 Node.js
npm install -g @example/mcp-server
# 手动编辑 ~/.claude/claude_desktop_config.json
# 重启 Claude Desktop
# 祈祷它能正常工作

之后：

下载一个 .mcpb 文件
双击用 Claude Desktop 打开
点击"安装"

无需终端、无需配置文件、无依赖冲突。

架构概览

Desktop Extension 是一个 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              # 可选：扩展图标

Desktop Extension 中唯一必需的文件是 manifest.json。Claude Desktop 处理所有复杂性：

内置运行时： Node.js 随 Claude Desktop 一起提供，消除了外部依赖
自动更新： 当有新版本可用时，扩展会自动更新
安全的密钥管理： API 密钥等敏感配置存储在操作系统密钥链中

清单包含人类可读的信息（名称、描述、作者）、功能声明（工具、提示）、用户配置和运行时要求。大多数字段是可选的，因此最简版本非常短，但实际上三种支持的扩展类型（Node.js、Python 和经典二进制/可执行文件）都需要包含文件：

json

{
  "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"
      ]
    }
  }
}

规范包含便捷选项，旨在使本地 MCP 服务器的安装和配置更加容易。服务器配置对象可以定义为同时支持通过模板字面量的用户自定义配置和平台特定的覆盖。扩展开发者可以详细定义他们希望从用户那里收集什么样的配置。

以下是清单如何辅助配置的具体示例。开发者声明用户需要提供 api_key。Claude 在用户提供该值之前不会启用扩展，自动将其保存在操作系统的密钥库中，并在启动服务器时透明地将 ${user_config.api_key} 替换为用户提供的值。类似地，${__dirname} 会被替换为扩展解压目录的完整路径。

json

{
  "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 可能如下所示：

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 的演练，以一个简单的文件系统服务器为例。

第一步：创建清单

为你的服务器初始化清单：

npx @anthropic-ai/mcpb init

这个交互式工具会询问你的服务器信息并生成完整的 manifest.json。要快速生成最基本的 manifest.json，可以使用 --yes 参数运行命令。

第二步：处理用户配置

如果你的服务器需要用户输入（如 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 Desktop 会：

显示用户友好的配置界面
在启用扩展前验证输入
安全存储敏感值
根据开发者配置，将配置作为参数或环境变量传递给你的服务器

以下是将用户配置作为环境变量传递的示例（也可以作为参数）：

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}"
   }
   }
}

第三步：打包扩展

将所有内容打包成 .mcpb 文件：

npx @anthropic-ai/mcpb pack

此命令：

验证你的清单
生成 .mcpb 归档文件

第四步：本地测试

将你的 .mcpb 文件拖入 Claude Desktop 的设置窗口。你会看到：

关于你扩展的人类可读信息
所需权限和配置
一个简单的"安装"按钮

高级功能

跨平台支持

扩展可以适配不同的操作系统：

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}：用户提供的配置
${HOME}、${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 Desktop 内置了精选的扩展目录。用户可以浏览、搜索并一键安装——无需搜索 GitHub 或审查代码。

Desktop Extension 规范以及 Claude 在 macOS 和 Windows 上的实现预计会随时间演进。

要提交你的扩展：

确保遵循提交表单中的指南
在 Windows 和 macOS 上进行测试
提交你的扩展
Anthropic 团队会审查质量和安全性

构建开放生态

Anthropic 表示致力于围绕 MCP 服务器的开放生态，并认为其被多个应用和服务普遍采纳的能力使社区受益。秉承这一承诺，他们将 Desktop Extension 规范、工具链以及 Claude 在 macOS 和 Windows 上实现自身 Desktop Extensions 支持所使用的 Schema 和关键函数开源。希望 MCPB 格式不仅能让本地 MCP 服务器对 Claude 更具可移植性，也能惠及其它 AI 桌面应用。

开源内容：

完整的 MCPB 规范
打包和验证工具
参考实现代码
TypeScript 类型和 Schema

这意味着：

对 MCP 服务器开发者： 一次打包，到处运行（任何支持 MCPB 的地方）
对应用开发者： 无需从零开始即可添加扩展支持
对用户： 在所有支持 MCP 的应用中获得一致体验

规范和工具链当前版本为 0.1，Anthropic 期待与更广泛的社区合作来演进和改进该格式。

安全和企业考量

扩展引入了新的安全考量，对企业尤为如此。预览版中内置了多项保障措施：

对用户

敏感数据保留在操作系统密钥链中
自动更新
可以审计已安装的扩展

对企业

组策略（Windows）和 MDM（macOS）支持
可以预装经批准的扩展
阻止特定扩展或发布者
完全禁用扩展目录
部署私有扩展目录

关于在组织内管理扩展的更多信息，请参阅 Anthropic 文档。

开始使用

对 MCP 服务器开发者： 查阅开发者文档或在本地 MCP 服务器目录中运行以下命令：

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

对 Claude Desktop 用户： 更新到最新版本并在设置中查找 Extensions 部分。

对企业： 查阅企业文档了解部署选项。

使用 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 服务器变得人人可用——而不仅仅是开发者。

在 Anthropic 内部，桌面扩展被用于分享高度实验性的 MCP 服务器。一个团队进行了实验，看看他们的模型在直接连接到 GameBoy 时能走多远，类似于他们的"Claude 玩 Pokemon"研究。他们使用 Desktop Extensions 打包了一个单独的扩展，打开流行的 PyBoy GameBoy 模拟器并让 Claude 接管控制。相信有无数机会可以将模型的能力与用户本地机器上已有的工具、数据和应用连接起来。

带来数千个 MCP 服务器的创造力，现在只需一次点击就能触达数百万用户。

提交你的扩展以供审核

文章未明确列出作者。

Desktop Extensions：Claude Desktop 的一键 MCP 服务器安装 ​

解决 MCP 安装难题 ​

介绍 Desktop Extensions ​

架构概览 ​

构建你的第一个扩展 ​

第一步：创建清单 ​

第二步：处理用户配置 ​

第三步：打包扩展 ​

第四步：本地测试 ​

高级功能 ​

跨平台支持 ​

动态配置 ​

功能声明 ​

扩展目录 ​

构建开放生态 ​

安全和企业考量 ​

对用户 ​

对企业 ​

开始使用 ​

使用 Claude Code 构建 ​

结论 ​

Desktop Extensions：Claude Desktop 的一键 MCP 服务器安装

解决 MCP 安装难题

介绍 Desktop Extensions

架构概览

构建你的第一个扩展

第一步：创建清单

第二步：处理用户配置

第三步：打包扩展

第四步：本地测试

高级功能

跨平台支持

动态配置

功能声明

扩展目录

构建开放生态

安全和企业考量

对用户

对企业

开始使用

使用 Claude Code 构建

结论