核验日期：2026-07-08

内容来源：Anthropic Engineering 官方技术博客。本文先作为 Claude Code 专区后台草稿入库，发布前应由内容人员复核标题、摘要、图片、来源链接与是否需要补充本站实践说明。

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

Desktop Extensions 让安装 MCP 服务器变得像点击按钮一样简单。我们分享其技术架构，以及创建优秀扩展的建议。

来源：https://www.anthropic.com/engineering/desktop-extensions
发布日期：2025-06-26

Desktop Extensions：为 Claude Desktop 一键安装 MCP 服务器题图

  • 文件扩展名更新

2025 年 9 月 11 日：Claude Desktop Extensions 现在使用 .mcpb（MCP Bundle）文件扩展名，而不是 .dxt。现有 .dxt 扩展仍会继续工作，但我们建议开发者今后为新扩展使用 .mcpb。所有功能保持不变，这纯粹是命名约定更新。

—

去年我们发布 Model Context Protocol（MCP）时，看到开发者构建了很多令人惊叹的本地服务器，让 Claude 能够访问从文件系统到数据库的各种内容。但我们一直听到同样的反馈：安装太复杂。用户需要开发者工具，必须手动编辑配置文件，而且经常卡在依赖问题上。

今天，我们推出 Desktop Extensions，这是一种新的打包格式，让安装 MCP 服务器像点击按钮一样简单。

解决 MCP 安装问题

本地 MCP 服务器为 Claude Desktop 用户解锁了强大能力。它们可以与本地应用交互、访问私有数据，并集成开发工具，同时让数据留在用户机器上。不过，当前安装流程造成了显著障碍：

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

这些摩擦点意味着，尽管 MCP 服务器能力强大，但对非技术用户来说仍基本不可及。

Desktop Extensions 介绍

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

之前：

# Install Node.js first
npm install -g @example/mcp-server
# Edit ~/.claude/claude_desktop_config.json manually
# Restart Claude Desktop
# Hope it works

复制

之后：

  1. 下载一个 .mcpb 文件
  2. 双击用 Claude Desktop 打开
  3. 点击 "Install"

就是这样。不需要终端，不需要配置文件，也没有依赖冲突。

架构概览

Desktop Extension 是一个 zip 归档，包含本地 MCP 服务器以及一个 manifest.json。这个 manifest 描述了 Claude Desktop 和其他支持 desktop extensions 的应用所需了解的一切。

extension.mcpb (ZIP archive)
├── manifest.json         # Extension metadata and configuration
├── server/               # MCP server implementation
│   └── [server files]
├── dependencies/         # All required packages/libraries
└── icon.png             # Optional: Extension icon

# Example: Node.js Extension
extension.mcpb
├── manifest.json         # Required: Extension metadata and configuration
├── server/               # Server files
│   └── index.js          # Main entry point
├── node_modules/         # Bundled dependencies
├── package.json          # Optional: NPM package definition
└── icon.png              # Optional: Extension icon

# Example: Python Extension
extension.mcpb (ZIP file)
├── manifest.json         # Required: Extension 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: Extension icon

复制

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

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

manifest 包含人类可读信息（例如名称、描述或作者）、功能声明（tools、prompts）、用户配置和运行时要求。大多数字段都是可选的，因此最小版本相当短，不过在实践中，我们预计三种受支持扩展类型（Node.js、Python，以及经典二进制文件/可执行文件）都会包含文件：

{
  "mcpb_version": "0.1",                    // MCPB spec version this manifest conforms to
  "name": "my-extension",                   // Machine-readable name (used for CLI, APIs)
  "version": "1.0.0",                       // Semantic version of your extension
  "description": "A simple MCP extension",  // Brief description of what the extension does
  "author": {                               // Author information (required)
    "name": "Extension Author"              // Author's name (required field)
  },
  "server": {                               // Server configuration (required)
    "type": "node",                         // Server type: "node", "python", or "binary"
    "entry_point": "server/index.js",       // Path to the main server file
    "mcp_config": {                         // MCP server configuration
      "command": "node",                    // Command to run the server
      "args": [                             // Arguments passed to the command
        "${__dirname}/server/index.js"      // ${__dirname} is replaced with the extension's directory
      ]
    }
  }
}

复制

manifest spec 中提供了许多便利选项，旨在让本地 MCP 服务器的安装和配置更容易。服务器配置对象可以用一种既容纳模板字面量形式的用户自定义配置、又容纳特定平台覆盖项的方式定义。扩展开发者可以详细定义希望从用户那里收集哪类配置。

让我们看一个 manifest 如何辅助配置的具体例子。在下面的 manifest 中，开发者声明用户需要提供 api_key。在用户提供该值之前，Claude 不会启用扩展；它会自动把该值保存在操作系统的秘密保险库中，并在启动服务器时透明地将 ${user_config.api_key} 替换为用户提供的值。类似地，${__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
    }
  }
}

复制

包含大多数可选字段的完整 manifest.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
    }
  }
}

复制

要查看扩展和 manifest，请参考 MCPB 仓库中的示例。

manifest.json 中所有必需和可选字段的完整规范，可以在我们的开源工具链中找到。

构建你的第一个扩展

让我们演示如何把一个现有 MCP 服务器打包为 Desktop Extension。我们会用一个简单的文件系统服务器作为示例。

第 1 步：创建 manifest

首先，为你的服务器初始化 manifest：

npx @anthropic-ai/mcpb init

复制

这个交互式工具会询问你的服务器相关信息，并生成完整的 manifest.json。如果你想快速生成最基础的 manifest.json，可以带上 --yes 参数运行该命令。

第 2 步：处理用户配置

如果你的服务器需要用户输入（例如 API key 或允许访问的目录），请在 manifest 中声明：

"user_config": {
  "allowed_directories": {
    "type": "directory",
    "title": "Allowed Directories",
    "description": "Directories the server can access",
    "multiple": true,
    "required": true,
    "default": ["${HOME}/Documents"]
  }
}

复制

Claude Desktop 会：

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

在下面的示例中，我们把用户配置作为环境变量传递，但它也可以作为参数传递。

"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 步：打包扩展

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

npx @anthropic-ai/mcpb pack

复制

这个命令会：

  1. 验证你的 manifest
  2. 生成 .mcpb 归档

第 4 步：本地测试

将你的 .mcpb 文件拖到 Claude Desktop 的 Settings 窗口中。你会看到：

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

高级功能

跨平台支持

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

"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 或审查代码。

虽然我们预计 Desktop Extension 规范，以及 Claude for macOS 和 Windows 中的实现都会随时间演进，但我们期待看到扩展以各种有创意的方式用于拓展 Claude 的能力。

提交你的扩展：

  1. 确保它遵循提交表单中的指南
  2. 在 Windows 和 macOS 上测试
  3. 提交你的扩展
  4. 我们的团队会进行质量和安全审查

构建开放生态

我们致力于 MCP 服务器周围的开放生态，并相信它被多个应用和服务普遍采用的能力已经让社区受益。出于这一承诺，我们会开源 Desktop Extension 规范、工具链，以及 Claude for macOS 和 Windows 用于实现自身 Desktop Extensions 支持的 schemas 和关键函数。我们希望 MCPB 格式不仅让本地 MCP 服务器对 Claude 更具可移植性，也让它们更容易被其他 AI 桌面应用采用。

我们会开源：

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

这意味着：

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

规范和工具链有意采用 0.1 版本号，因为我们期待与更广泛社区一起演进和改变这一格式。我们期待听到你的反馈。

安全和企业考量

我们理解扩展会带来新的安全考量，尤其是对企业而言。在 Desktop Extensions 预览版中，我们内置了几项防护措施：

对用户

  • 敏感数据保留在操作系统钥匙串中
  • 自动更新
  • 能够审计已安装哪些扩展

对企业

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

关于如何在组织内管理扩展的更多信息，请参见我们的文档。

开始使用

准备构建自己的扩展了吗？可以这样开始：

对于 MCP 服务器开发者：阅读我们的开发者文档，或者在你的本地 MCP 服务器目录中直接运行以下命令：

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

复制

对于 Claude Desktop 用户：更新到最新版本，并在 Settings 中查找 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 服务器对所有人可用，而不只是开发者。

在内部，我们使用 desktop extensions 分享高度实验性的 MCP 服务器，有些有趣，有些实用。一个团队做了实验，想看看当模型直接连接到 GameBoy 时能走多远，这类似我们的 “Claude plays Pokémon” 研究。我们使用 Desktop Extensions 打包了一个单一扩展，它会打开流行的 PyBoy GameBoy 模拟器，并让 Claude 接管控制。我们相信，将模型能力连接到用户本地机器上已有的工具、数据和应用，会带来无数机会。

显示 PyBoy MCP 和 Super Mario Land 开始屏幕的桌面

我们迫不及待想看到你会构建什么。带来数千个 MCP 服务器的同一种创造力，现在可以通过一次点击触达数百万用户。准备好分享你的 MCP 服务器了吗？提交你的扩展以供审查。

带复杂几何形状和细致表面纹理的互锁拼图块

想了解更多？

探索课程