人工智能文摘

桌面扩展：为 Claude Desktop 一键安装 MCP 服务器

Desktop Extensions: One-click MCP server installation for Claude Desktop | Anthropic | 2025-06-26

桌面扩展让安装 MCP 服务器像点一下按钮一样简单。本文将分享其技术架构，并给出打造优秀扩展的实用建议。

  • 文件扩展名更新

2025 年 9 月 11 日

Claude 桌面扩展现在使用 .mcpb（MCP Bundle）文件扩展名来取代 .dxt。现有的 .dxt 扩展仍然可以正常工作，但我们建议开发者在今后的新扩展中使用 .mcpb。所有功能保持不变——这仅是命名约定的更新。

—

当我们在去年发布 Model Context Protocol（MCP）时，看到开发者构建了出色的本地服务器，让 Claude 能访问从文件系统到数据库的各种资源。但我们也反复听到同样的反馈：安装过程太复杂。用户需要开发者工具，必须手动编辑配置文件，还常常卡在依赖问题上。

今天，我们发布了“桌面扩展”——一种全新的打包格式，让安装 MCP 服务器像点击一下按钮一样简单。

解决 MCP 安装难题

本地 MCP 服务器为 Claude 桌面版用户解锁强大能力：它们可以与本地应用交互、访问私有数据，并与开发工具集成——同时数据始终保留在用户的机器上。然而，目前的安装流程设置了不小的门槛：

  • 需要开发者工具 ：用户需要先安装 Node.js、Python 或其他运行时
  • 手动配置 ：每个服务器都要手动编辑 JSON 配置文件
  • 依赖管理 ：用户需要自行解决包冲突与版本不匹配
  • 缺少发现机制 ：想找到有用的 MCP 服务器往往得在 GitHub 上到处搜
  • 更新复杂 ：保持服务器最新通常意味着手动重新安装

这些摩擦点导致 MCP 服务器虽强大，却难以触达非技术用户。

介绍桌面扩展

桌面扩展（.mcpb 文件）通过把整个 MCP 服务器（包括所有依赖）打包为一个可安装包，解决了上述问题。对用户来说，体验有如下改变：

之前：

# 先安装 Node.js 
npm install -g @example/mcp-server 
# 手动编辑 ~/.claude/claude_desktop_config.json 
# 重启 Claude 桌面应用 
# 祝你好运

复制

现在：

  1. 下载一个 .mcpb 文件
  2. 双击用 Claude 桌面应用打开
  3. 点击“安装”

就是这样。无需终端、无需配置文件、也没有依赖冲突。

架构概览

一个桌面扩展本质上是一个 zip 压缩包，包含本地 MCP 服务器以及一个 manifest.json，它描述了 Claude 桌面应用和其他支持桌面扩展的应用所需的一切信息。

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              # 可选：扩展图标

复制

桌面扩展唯一必需的文件是 manifest.json。Claude 桌面应用会处理其余复杂性：

  • 内置运行时 ：Claude 桌面应用自带 Node.js，消除外部依赖
  • 自动更新 ：扩展在有新版本时会自动更新
  • 安全的密钥管理 ：API Key 等敏感配置存放在操作系统钥匙串中

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

{
  "mcpb_version": "0.1",          
  "name": "my-extension",          
  "version": "1.0.0",             
  "author": {                       
    "name": "Extension Author"     
  },                                  
  "server": {                        
    "type": "node",                
    "entry_point": "server/index.js"
  }                                   
}

复制

manifest 规范中提供了许多便利选项，旨在简化本地 MCP 服务器的安装与配置。服务器配置对象既可以通过模板字面量为用户配置预留空间，也可以进行平台特定的覆盖。扩展开发者可以详细定义希望向用户收集哪些配置。

下面通过一个具体示例来说明 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 服务器打包为桌面扩展。

第 1 步：创建 manifest

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

npx @anthropic-ai/mcpb init

复制

该交互式工具会询问你的服务器信息，并生成一个完整的 manifest.json。如果你想“极速通关”，也可以在命令中加上 --yes 参数来生成最基础的 manifest.json。

第 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 桌面应用会：

  • 显示友好的配置界面
  • 在启用扩展前校验输入
  • 安全保存敏感值
  • 按开发者配置将用户配置传递给服务器（作为参数或环境变量）

在下面的示例中，我们通过环境变量传递用户配置；当然，也可以通过参数传递。

"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 桌面应用的“设置”窗口。你会看到：

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

高级特性

跨平台支持

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

"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 桌面应用中内置了一个经过策展的扩展目录。用户可以浏览、搜索，并一键安装——无需在 GitHub 上四处寻找或亲自审阅代码。

虽然我们预计桌面扩展规范以及 Claude 在 macOS 与 Windows 上的实现都会随时间演进，但我们很期待看到大家用扩展以多种创意方式拓展 Claude 的能力边界。

提交你的扩展之前：

  1. 确保符合提交流程中的指南
  2. 在 Windows 与 macOS 上完成测试
  3. 提交你的扩展
  4. 我们的团队会进行质量与安全审查

构建开放生态

我们致力于围绕 MCP 服务器构建开放生态，并相信其可被多种应用与服务普遍采用的能力已经造福了社区。秉持这一承诺，我们将桌面扩展的规范、工具链，以及 Claude 在 macOS 与 Windows 上实现桌面扩展支持所使用的关键 Schema 与函数开源。我们希望 MCPB 格式不仅让本地 MCP 服务器在 Claude 之间更易移植，也能惠及其他 AI 桌面应用。

我们将开源：

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

这意味着：

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

我们将该规范与工具链的版本刻意定为 0.1，因为我们期待与更广泛的社区共同迭代、演进这一格式。期待听到你的反馈。

安全与企业场景

我们理解扩展会带来新的安全考量，尤其是在企业环境中。在桌面扩展预览版中，我们内置了多项防护：

面向用户

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

面向企业

  • 支持组策略（Windows）与 MDM（macOS）
  • 能预装批准的扩展
  • 可将特定扩展或发布者加入黑名单
  • 可完全禁用扩展目录
  • 可部署私有扩展目录

关于如何在你的组织内管理扩展，请参阅我们的文档。

快速上手

准备好构建你自己的扩展了吗？从这里开始：

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

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

复制

对 Claude 桌面用户 ：更新到最新版本，并在设置中找到 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.

复制

结语

桌面扩展代表了用户与本地 AI 工具交互方式的一次根本性转变。通过消除安装摩擦，我们让强大的 MCP 服务器对所有人都触手可及——不仅仅是开发者。

在内部，我们用桌面扩展来分享一些高度实验性的 MCP 服务器——有的很有趣，有的很实用。比如有个团队尝试把模型直接接到 GameBoy 上，看看它能走多远，这与我们的“Claude 玩宝可梦”研究类似。我们用桌面扩展打了一个包，打开流行的 PyBoy GameBoy 模拟器，并让 Claude 接管。我们相信，存在无数机会把模型能力连接到用户本地已经拥有的工具、数据与应用上。

一台桌面设备显示 PyBoy MCP，画面为《超级马里奥乐园》开始界面

我们迫不及待想看到你的创作。同样的创造力曾让数千个 MCP 服务器涌现，如今只需一次点击，它们就能触达数以百万计的用户。准备分享你的 MCP 服务器了吗？提交扩展以供审核。

想进一步了解？

在 Anthropic Academy 学习 API 开发、Model Context Protocol 与 Claude Code 课程，结课可获证书。

浏览课程

订阅开发者通讯

产品更新、操作指南、社区聚光灯等内容，每月发送至你的收件箱。

如果你希望收到我们的每月开发者通讯，请留下你的电子邮箱地址。你可以随时取消订阅。

查看原文 →