Anthropic · 工程博客

Claude Desktop Extensions：为 Claude Desktop 一键安装 MCP server

Claude Desktop Extensions: One-click MCP server installation for Claude Desktop

二〇二六年五月八日 · 英文原文

摘要

Anthropic 发布 Claude Desktop Extensions，将本地 MCP server 及依赖打包为 .mcpb（MCP Bundle）文件，取代 .dxt 命名；manifest.json 描述配置、runtime、tools、prompts 和用户参数。工具链支持 init、pack、验证与自动更新，并提供 OS keychain、Group Policy、MDM 等管理能力。

文件扩展名更新

Sep 11, 2025 Claude Desktop Extensions 现在使用 .mcpb（MCP Bundle）文件扩展名，而不是 .dxt。现有 .dxt 扩展仍将继续可用，但我们建议开发者今后为新扩展使用 .mcpb。所有功能保持不变——这只是命名约定的更新。

—

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

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

解决 MCP 安装问题

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

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

这些摩擦点意味着，尽管 MCP server 功能强大，但对非技术用户来说仍然很难使用。

介绍 Desktop Extensions

Desktop Extensions（.mcpb 文件）通过将整个 MCP server（包括所有依赖）打包成一个可安装 package 来解决这些问题。对用户来说，变化如下：

之前：

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

之后：

下载一个 .mcpb 文件
双击，用 Claude Desktop 打开
点击“Install”

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

架构概览

Desktop Extension 是一个 zip archive，包含本地 MCP server 以及一个 manifest.json，后者描述了 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 会处理所有复杂性：

内置 runtime：我们随 Claude Desktop 一起提供 Node.js，消除外部依赖
自动更新：当有新版本可用时，Extensions 会自动更新
安全的 secrets：API key 等敏感配置会存储在 OS keychain 中

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

{
  "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 server 的安装和配置更容易。server 配置对象可以用一种方式定义，既能通过 template literals 为用户自定义配置留出空间，也能支持特定平台的 overrides。Extension 开发者可以详细定义他们希望从用户那里收集哪类配置。

我们来看一个 manifest 如何辅助配置的具体示例。在下面的 manifest 中，开发者声明用户需要提供一个 api_key。在用户提供该值之前，Claude 不会启用该 extension；它会自动将其保存在操作系统的 secret vault 中，并在启动 server 时透明地将 ${user_config.api_key} 替换为用户提供的值。类似地，${__dirname} 会被替换为 extension 解包目录的完整路径。

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

要查看 extension 和 manifest，请参考 MCPB repository 中的示例。

manifest.json 中所有必需和可选字段的完整 specification，可在我们的 open-source toolchain 中找到。

构建你的第一个 extension

下面我们演示如何将一个现有 MCP server 打包为 Desktop Extension。我们将以一个简单的文件系统 server 为例。

Step 1：创建 manifest

首先，为你的 server 初始化一个 manifest：

npx @anthropic-ai/mcpb init

这个交互式工具会询问你的 server 相关信息，并生成完整的 manifest.json。如果你想快速得到最基础的 manifest.json，可以在命令中添加 --yes 参数。

Step 2：处理用户配置

如果你的 server 需要用户输入（例如 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
在启用 extension 前验证输入
安全地存储敏感值
根据开发者配置，将配置作为参数或环境变量传递给你的 server

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

"server": {
   "type": "node",
   "entry_point": "server/index.js",
   "mcp_config": {
   "command": "node",
   "args": ["${__dirname}/server/index.js"],
   "env": {
      "ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"
   }
   }
}

Step 3：打包 extension

将所有内容打包成一个 .mcpb 文件：

npx @anthropic-ai/mcpb pack

此命令会：

验证你的 manifest
生成 .mcpb archive

Step 4：本地测试

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

关于你的 extension 的人类可读信息
所需权限和配置
一个简单的“Install”按钮

高级功能

跨平台支持

Extensions 可以适配不同操作系统：

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

动态配置

使用 template literals 表示 runtime 值：

${__dirname}：Extension 的安装目录
${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"]
  }
]

Extension 目录

我们将在 Claude Desktop 中内置一个经过 curated 的 extension 目录。用户可以浏览、搜索，并一键安装——无需搜索 GitHub 或审查代码。

虽然我们预计 Desktop Extension specification 以及 Claude for macOS 和 Windows 中的实现会随着时间演进，但我们期待看到 extensions 以多种方式创造性地扩展 Claude 的能力。

提交你的 extension：

确保它遵循提交表单中的 guidelines
在 Windows 和 macOS 上测试
提交你的 extension
我们的团队会进行质量和安全审查

构建开放生态

我们致力于围绕 MCP server 建设开放生态，并相信它能被多个应用和服务普遍采用，这已经让社区受益。基于这一承诺，我们将开源 Desktop Extension specification、toolchain，以及 Claude for macOS 和 Windows 用于实现自身 Desktop Extensions 支持的 schemas 和关键函数。我们希望 MCPB 格式不仅能让本地 MCP server 更便于在 Claude 中移植，也能服务于其他 AI desktop 应用。

我们将开源：

完整的 MCPB specification
打包和验证工具
Reference implementation code
TypeScript types 和 schemas

这意味着：

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

我们有意将 specification 和 toolchain 的版本定为 0.1，因为我们期待与更广泛的社区一起演进和改变这一格式。期待听到你的反馈。

安全与企业考虑

我们理解 extensions 会引入新的安全考虑，尤其是对企业而言。在 Desktop Extensions 的 preview release 中，我们内置了多项保护措施：

对用户

敏感数据保留在 OS keychain 中
自动更新
能够审计已安装的 extensions

对企业

支持 Group Policy（Windows）和 MDM（macOS）
能够预安装已批准的 extensions
可阻止特定 extensions 或 publishers
可完全禁用 extension 目录
部署私有 extension 目录

关于如何在组织内管理 extensions 的更多信息，请参阅我们的 documentation。

开始使用

准备构建你自己的 extension？可以这样开始：

对 MCP server 开发者：阅读我们的 developer documentation——或者直接在你的本地 MCP servers 目录中运行以下命令：

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

对 Claude Desktop 用户：更新到最新版本，并在 Settings 中查找 Extensions 部分

对企业：阅读我们的企业文档以了解部署选项

使用 Claude Code 构建

在 Anthropic 内部，我们发现 Claude 很擅长在很少干预的情况下构建 extensions。如果你也想使用 Claude Code，我们建议你简要说明希望 extension 做什么，然后在 prompt 中添加以下上下文：

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 server 对所有人可用，而不仅仅是开发者。

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

图片 1：一个桌面，显示带有 Super Mario Land 开始画面的 PyBoy MCP

我们期待看到你构建的内容。曾经带来数千个 MCP servers 的创造力，现在可以通过一次点击触达数百万用户。准备好分享你的 MCP server 了吗？提交你的 extension 以供审核。

译自 Anthropic · 工程博客 · 录于二〇二六年五月八日