Desktop Extensions 桌面扩展

原文：Desktop Extensions: One-click MCP server installation for Claude Desktop 发布时间：2025年6月26日更新：2025年9月11日 - 文件扩展名从 .dxt 更新为 .mcpb

概述

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

解决的问题

MCP 安装痛点

本地 MCP 服务器为 Claude Desktop 用户解锁了强大功能，但当前安装过程存在显著障碍：

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

解决方案

之前：

# 先安装 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 archive)
├── manifest.json         # 扩展元数据和配置
├── server/               # MCP 服务器实现
│   └── [server files]    
├── dependencies/         # 所有必需的包/库
└── icon.png             # 可选：扩展图标

# Node.js 扩展示例
extension.mcpb
├── manifest.json         # 必需：扩展元数据和配置
├── server/               # 服务器文件
│   └── index.js          # 主入口点
├── node_modules/         # 打包的依赖
├── package.json          # 可选：NPM 包定义
└── icon.png              # 可选：扩展图标

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

核心特性

内置运行时：我们随 Claude Desktop 一起提供 Node.js，消除外部依赖
自动更新：当有新版本可用时，扩展会自动更新
安全密钥：敏感配置如 API 密钥存储在 OS 密钥链中

Manifest 配置

最小配置示例

{
  "mcpb_version": "0.1",                    // 此清单符合的 MCPB 规范版本
  "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} 替换为扩展目录
      ]                              
    }
  }
}

用户配置示例

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

完整配置示例

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

开发指南

步骤 1：初始化扩展

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

步骤 2：创建 manifest.json

按照上述配置示例创建清单文件。

步骤 3：打包扩展

npx @anthropic-ai/mcpb pack

此命令会：

验证您的清单
生成 .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 或审查代码。

提交扩展

确保遵循提交表单中的指南
在 Windows 和 macOS 上测试
提交您的扩展
我们的团队审查质量和安全性

构建开放生态系统

我们致力于围绕 MCP 服务器的开放生态系统，并相信其被多个应用程序和服务普遍采用的能力使社区受益。

开源内容

我们正在开源：

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

这意味着：

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

安全和企业考虑

用户安全

敏感数据保留在 OS 密钥链中
自动更新
能够审计已安装的扩展

企业安全

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

使用 Claude Code 构建

如果您想使用 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.

开始使用

对于 MCP 服务器开发者

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

对于 Claude Desktop 用户

更新到最新版本并在设置中查找扩展部分

对于企业

查看我们的企业文档了解部署选项

CloudObsidian

Explorer

Desktop Extensions桌面扩展