MCP 打包文件 (MCPB)

⚠️ 重要通知：该项目正从 DXT（桌面扩展）更名为 MCPB（MCP 打包文件）

如果您正在寻找 DXT 工具，它们现已更名为 MCPB。请更新您的依赖项和工具链：

• dxt CLI 现在为 mcpb
• .dxt 文件现在是 .mcpb 文件
• @anthropic-ai/dxt 包将被移动到 @anthropic-ai/mcpb

MCP 打包文件（.mcpb）是包含本地 MCP 服务器和描述该服务器及其功能的 manifest.json 的 ZIP 压缩包。其格式与 Chrome 扩展（.crx）或 VS Code 扩展（.vsix）类似，允许最终用户只需单击即可安装本地 MCP 服务器。

本仓库提供三个组件：MANIFEST.md 中的打包规范、用于创建打包文件的 CLI 工具（参见 CLI.md），以及 Claude for macOS 和 Windows 用来加载和验证 MCPB 打包文件的代码（src/index.ts）。

• 对于本地 MCP 服务器的开发者，我们的目标是让这些服务器的分发和安装更加便捷。
• 对于支持本地 MCP 服务器的应用程序开发者，我们希望使添加对 MCPB 打包文件的支持变得简单易行。

Claude for macOS 和 Windows 使用本仓库中的代码，实现了本地 MCP 服务器的一键安装，并提供了一系列用户友好的功能——例如自动更新、轻松配置 MCP 服务器及其所需的变量和参数，以及一个精选目录。我们致力于围绕 MCP 服务器的开放生态系统，并相信其能够被多种应用程序和服务普遍采用，这将为那些希望将 AI 工具与其他应用和服务连接起来的开发者带来益处。因此，我们决定开源 MCP 打包文件的规范、工具链，以及 Claude for macOS 和 Windows 用来实现自身对 MCP 打包文件支持的模式和关键函数。我们希望 mcpb 格式不仅能让本地 MCP 服务器在 Claude 中更易于移植，也能被其他 AI 桌面应用程序所使用。

针对打包文件开发者

从根本上说，MCPB 只是一个简单的 ZIP 文件，其中包含了您的整个 MCP 服务器和一个 manifest.json。因此，将本地 MCP 服务器转换为打包文件非常简单：您只需将所有必要的文件放入一个文件夹中，创建一个 manifest.json，然后生成一个压缩包即可。

为了简化这一过程，本包提供了一个 CLI 工具，可以帮助您同时创建 manifest.json 和最终的 .mcpb 文件。要安装它，请运行：

npm install -g @anthropic-ai/mcpb

1. 在包含您的本地 MCP 服务器的文件夹中，运行 mcpb init。此命令将引导您完成 manifest.json 的创建。
2. 运行 mcpb pack 来创建一个 mcpb 文件。
3. 现在，任何支持 MCPB 的应用程序都可以运行您的本地 MCP 服务器。例如，您可以使用 Claude for macOS 和 Windows 打开该文件，以显示安装对话框。

您可以在 MANIFEST.md 中找到 manifest.json 的完整规范及其所有必填和可选字段。打包文件的示例可在 examples 目录中找到。

面向 AI 工具的提示模板

像 Claude Code 这样的 AI 工具在了解规范的情况下，特别擅长创建 MCP 打包文件。当您要求 AI 编码工具构建一个打包文件时，应简要说明您的打包文件旨在实现什么功能，然后在您的指令中加入以下内容：

我想将其构建为 MCP 打包文件，简称“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 规范，以确保与生态系统的兼容性。

目录结构

最小化打包文件

唯一必需的文件是 manifest.json。

示例：Node.js 打包文件

bundle.mcpb (ZIP 文件)
├── manifest.json         # 必需：打包文件元数据和配置
├── server/               # 服务器文件
│   └── index.js          # 主入口点
├── node_modules/         # 打包的依赖项
├── package.json          # 可选：NPM 包定义
├── icon.png              # 可选：打包文件图标
└── assets/               # 可选：附加资源

示例：Python 打包文件

bundle.mcpb (ZIP 文件)
├── manifest.json         # 必需：打包文件元数据和配置
├── server/               # 服务器文件
│   ├── main.py           # 主入口点
│   └── utils.py          # 辅助模块
├── lib/                  # 打包的 Python 库
├── requirements.txt      # 可选：Python 依赖列表
└── icon.png              # 可选：打包文件图标

示例：二进制打包文件

bundle.mcpb (ZIP 文件)
├── manifest.json         # 必需：打包文件元数据和配置
├── server/               # 服务器文件
│   ├── my-server         # Unix 可执行文件
│   ├── my-server.exe     # Windows 可执行文件
└── icon.png              # 可选：打包文件图标

语言选择建议

我们建议使用 Node.js 实现 MCP 服务器，而不是 Python，以减少安装上的麻烦。Node.js 已预装在 Claude for macOS 和 Windows 中，这意味着您的打包文件可以即插即用，无需用户额外安装 Python 运行时环境（也无需您手动打包这些环境）。

依赖打包

UV 运行时（v0.4+）：

• 在 manifest 中使用 server.type = "uv"
• 包含带有依赖项的 pyproject.toml 文件（无需捆绑包）
• 主机应用会自动管理 Python 和依赖项
• 跨平台运行，无需用户安装 Python
• 参见 examples/hello-world-uv

传统 Python 捆绑包：

• 在 manifest 中使用 server.type = "python"
• 将所有所需包捆绑到 server/lib/ 目录中
• 或将完整的虚拟环境捆绑到 server/venv/ 目录中
• 使用 pip-tools、poetry 或 pipenv 等工具创建可复现的捆绑包
• 通过 mcp_config.env 设置 PYTHONPATH，以包含捆绑的包
• 限制：无法跨平台地捆绑编译型依赖（例如 pydantic，MCP Python SDK 所需的依赖）

Node.js 捆绑包：

• 运行 npm install --production 来生成 node_modules
• 将整个 node_modules 目录与您的捆绑包一起打包
• 使用 npm ci 或 yarn install --frozen-lockfile 以实现可复现的构建
• 服务器入口点在 manifest.json 的 server.entry_point 中指定

二进制捆绑包：

• 优先使用静态链接以获得最大兼容性
• 如果使用动态链接，请包含所有所需的共享库
• 在没有开发工具的干净系统上进行测试

贡献

我们欢迎贡献！请参阅我们的 贡献指南 以获取详细信息。

开发环境设置

# 克隆仓库
git clone https://github.com/anthropics/mcpb.git
cd mcpb

# 安装依赖
yarn

# 构建项目
yarn build

# 运行测试
yarn test

发布流程

1. 更新 package.json 中的版本号
2. 创建包含版本号更新的拉取请求
3. 合并后，在 GitHub 上创建发布版本
4. 软件包将自动发布到 npm

许可证

本项目的新贡献采用 Apache License 2.0 许可证，现有代码则采用 MIT 许可证——详情请参阅 LICENSE 文件。

MCPB (MCP Bundles) 快速上手指南

MCPB (MCP Bundles) 是一种用于分发本地 MCP 服务器的打包格式（类似 Chrome 的 .crx 或 VS Code 的 .vsix）。它允许用户通过单个文件一键安装和运行本地 MCP 服务器。本项目原名 DXT，现已更名为 MCPB。

环境准备

• 操作系统: macOS, Windows, 或 Linux
• 运行时依赖:
  • Node.js: 必须安装 (推荐 LTS 版本)，用于运行 CLI 工具及 Node.js 类型的 MCP 服务。
  • npm 或 yarn: 用于安装 CLI 工具。
• 可选依赖 (取决于你开发的服务器类型):
  • Python: 若开发 Python 版服务器，建议安装 Python 3.8+。若使用 uv 运行时 (推荐)，宿主应用会自动管理，无需用户预装。
  • 编译器: 若打包二进制文件，需在干净系统中测试静态链接。

💡 语言选择建议: 推荐使用 Node.js 开发 MCP 服务器。因为 Claude 桌面端内置了 Node.js 环境，用户无需额外安装任何运行时即可直接运行你的 Bundle，体验最流畅。

安装步骤

安装全局 CLI 工具 mcpb：

npm install -g @anthropic-ai/mcpb

(国内用户若遇网络问题，可配置 npm 镜像源后重试)

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/mcpb

验证安装：

mcpb --version

基本使用

以下是将现有的本地 MCP 服务器打包为 .mcpb 文件的最简流程。

1. 初始化项目

进入包含你 MCP 服务器代码的目录，运行初始化命令。该命令会引导你生成必需的 manifest.json 配置文件。

mcpb init

按提示填写服务器名称、描述、入口文件等信息。

2. 打包 Bundle

确保所有依赖已安装（例如 Node.js 项目需先运行 npm install --production 生成 node_modules），然后执行打包命令：

mcpb pack

执行成功后，当前目录下将生成一个 .mcpb 文件（本质是包含 manifest.json 和服务端代码的 ZIP 包）。

3. 安装与测试

生成的 .mcpb 文件可直接在支持该格式的应用中使用。

• Claude 桌面端 (macOS/Windows): 双击生成的 .mcpb 文件，或在 Claude 设置中选择“安装 MCP 服务器”并导入该文件，即可完成一键安装。
• 其他应用: 任何实现了 MCPB 规范的应用均可加载此文件。

目录结构参考

一个标准的 Node.js Bundle 结构如下：

bundle.mcpb (ZIP 归档)
├── manifest.json         # [必需] 元数据配置
├── server/               # 服务端代码
│   └── index.js          # 入口文件
├── node_modules/         # [必需] 生产环境依赖
├── package.json          # [可选] NPM 定义
└── icon.png              # [可选] 图标