dxt

MCP Bundles（MCPB）

⚠️ 重要通知：此项目正从 DXT（Desktop Extensions）更名为 MCPB（MCP Bundles）

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

• dxt CLI 现在是 mcpb
• .dxt 文件现在是 .mcpb 文件
• @anthropic-ai/dxt 软件包将迁移为 @anthropic-ai/mcpb

MCP Bundles（.mcpb）是 ZIP 归档文件，其中包含本地 MCP 服务和用于描述该服务及其功能的 manifest.json。这种格式在理念上类似于 Chrome 扩展（.crx）或 VS Code 扩展（.vsix），让最终用户能够一键安装本地 MCP 服务。

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

• 对于本地 MCP 服务的开发者，我们致力于让这些服务的分发和安装更加便捷
• 对于支持本地 MCP 服务的应用开发者，我们致力于让应用轻松支持 MCPB Bundle

Claude for macOS 和 Windows 使用此仓库中的代码来支持一键安装本地 MCP 服务，并提供多项便于最终用户使用的功能，例如自动更新、轻松配置 MCP 服务及其所需的变量和参数，以及精选目录。我们致力于构建围绕 MCP 服务的开放生态系统，并相信，多种应用和服务都能普遍采用 MCP 服务，这将有助于开发者将 AI 工具连接到其他应用和服务。因此，我们将开源 MCP Bundle 规范、工具链，以及 Claude for macOS 和 Windows 用于实现 MCP Bundle 支持的架构和关键功能。我们希望 mcpb 格式不只让本地 MCP 服务更便于在 Claude 中移植，也能在其他 AI 桌面应用中发挥作用。

面向 Bundle 开发者

从本质上说，MCPB 是简单的 ZIP 文件，其中包含完整的 MCP 服务和一个 manifest.json。因此，将本地 MCP 服务打包成 Bundle 很简单：只需将所有必需文件放入一个文件夹，创建 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 的完整规范，以及所有必填和可选字段。Bundle 示例可在 examples 中找到。

AI 工具提示词模板

Claude Code 等 AI 工具在了解规范后，特别擅长创建 MCP bundle。提示 AI 编码工具构建 bundle 时，请简要说明 bundle 的目标，然后将以下内容添加到指令中。

我想将其构建为 MCP Bundle，简称“MCPB”。请按照以下步骤操作：

1. 仔细阅读规范：
   • https://github.com/anthropics/mcpb/blob/main/README.md - MCPB 架构概览、功能和集成模式
   • https://github.com/anthropics/mcpb/blob/main/MANIFEST.md - 完整的 bundle 清单结构和字段定义
   • https://github.com/anthropics/mcpb/tree/main/examples - 参考实现，包括“Hello World”示例
2. 创建规范的 bundle 结构：
   • 遵循 MANIFEST.md 规范生成有效的 manifest.json
   • 使用 @modelcontextprotocol/sdk 实现 MCP 服务，并正确定义工具
   • 包含完善的错误处理、安全措施和超时管理
3. 遵循最佳开发实践：
   • 通过 stdio 传输实现规范的 MCP 协议通信
   • 为工具设置清晰的模式、验证机制和一致的 JSON 响应
   • 利用此 bundle 将在本地运行这一特点
   • 添加适当的日志记录和调试功能
   • 提供完善的文档和设置说明
4. 测试注意事项：
   • 验证所有工具调用均返回结构正确的响应
   • 确认清单能够正确加载，且主机集成正常工作

生成可立即测试的完整生产级代码。重点关注防御性编程、清晰的错误消息，并严格遵循 MCPB 规范，以确保与生态系统兼容。

目录结构

最简 Bundle

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

示例：Node.js Bundle

bundle.mcpb (ZIP file)
├── manifest.json         # Required: Bundle metadata and configuration
├── server/               # Server files
│   └── index.js          # Main entry point
├── node_modules/         # Bundled dependencies
├── package.json          # Optional: NPM package definition
├── icon.png              # Optional: Bundle icon
└── assets/               # Optional: Additional assets

示例：Python Bundle

bundle.mcpb (ZIP file)
├── manifest.json         # Required: Bundle metadata and configuration
├── server/               # Server files
│   ├── main.py           # Main entry point
│   └── utils.py          # Additional modules
├── lib/                  # Bundled Python packages
├── requirements.txt      # Optional: Python dependencies list
└── icon.png              # Optional: Bundle icon

示例：二进制 Bundle

bundle.mcpb (ZIP file)
├── manifest.json         # Required: Bundle metadata and configuration
├── server/               # Server files
│   ├── my-server         # Unix executable
│   ├── my-server.exe     # Windows executable
└── icon.png              # Optional: Bundle icon

语言选择建议

我们建议使用 Node.js 而非 Python 实现 MCP 服务，以减少安装阻碍。 macOS 和 Windows 版 Claude 均附带 Node.js，因此无需用户安装额外的 Python 运行时（也无需你手动打包这些运行时），bundle 即可开箱即用。

打包依赖项

UV 运行时（v0.4+）：

• 在清单中使用 server.type = "uv"
• 添加包含依赖项的 pyproject.toml（无需打包软件包）
• 主机应用会自动管理 Python 和依赖项
• 跨平台可用，用户无需安装 Python
• 参见 examples/hello-world-uv

Python Bundle（传统方式）：

• 在清单中使用 server.type = "python"
• 将所有必需的软件包打包到 server/lib/ 目录中
• 或将完整的虚拟环境打包到 server/venv/ 中
• 使用 pip-tools、poetry 或 pipenv 等工具创建可复现的 bundle
• 通过 mcp_config.env 设置 PYTHONPATH，使其包含打包的软件包
• 限制：无法以可移植的方式打包编译型依赖项（例如 MCP Python SDK 所需的 pydantic）

Node.js Bundle：

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

二进制 Bundle：

• 为实现最高兼容性，优先使用静态链接
• 如果使用动态链接，请包含所有必需的共享库
• 在未安装开发工具的干净系统上进行测试

贡献

欢迎贡献！详情请参阅我们的贡献指南。

开发环境设置

# Clone the repository
git clone https://github.com/anthropics/mcpb.git
cd mcpb

# Install dependencies
yarn

# Build the project
yarn build

# Run tests
yarn test

发布流程

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

许可证

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