跳转至

Claude Desktop Extensions：一键安装 MCP Server

  • 原文链接：https://www.anthropic.com/engineering/desktop-extensions [60]
  • 发布时间：2025-06-26
  • 作者：未署名

Desktop Extensions 把 MCP server 打包成可双击安装的单文件，让“本地能力”真正易用。[60]

文件扩展名更新（2025-09-11）： Claude Desktop Extensions 现在使用 .mcpb（MCP Bundle）替代 .dxt。现有 .dxt 仍可用，但建议新扩展统一采用 .mcpb。功能不变，仅为命名约定更新。[60]

去年我们发布 MCP 后，开发者构建了大量本地服务器，让 Claude 能访问文件系统、数据库等。但最常见反馈是：安装太复杂。用户需要开发者工具、手动改配置，还经常卡在依赖问题上。[60]

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

解决 MCP 安装难题

本地 MCP server 能让 Claude Desktop 访问本地应用、私有数据与开发工具，同时数据留在用户机器上。但当前安装流程存在多重障碍：[60]

  • 需要开发者工具：必须安装 Node.js、Python 或其他运行时
  • 手工配置：每个 server 都要编辑 JSON 配置
  • 依赖管理痛苦：包冲突与版本不匹配频繁出现
  • 缺乏发现机制：寻找服务器只能靠 GitHub 搜索
  • 更新复杂：升级往往需要手动重装

这些摩擦让 MCP server 的能力难以触达非技术用户。[60]

引入 Desktop Extensions

Desktop Extensions（.mcpb 文件）把 MCP server 连同所有依赖打包成单一安装包。用户体验从这样：[60]

以前：

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

变成这样：[60]

  1. 下载 .mcpb
  2. 双击用 Claude Desktop 打开
  3. 点击 “Install”

就这么简单。无需终端、无需配置、无依赖冲突。[60]

架构概览

Desktop Extension 本质是一个 zip 包，包含 MCP server 与 manifest.json，后者描述 Claude Desktop 需要的元信息与配置：[60]

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 会处理剩余复杂性：[60]

  • 内置运行时：Claude Desktop 自带 Node.js
  • 自动更新：新版本可自动更新
  • 安全密钥：敏感配置（如 API key）存放在 OS keychain

manifest 中包含：人类可读信息（名称、描述、作者）、功能声明（工具/提示词）、用户配置与运行时要求。多数字段可选，最小版本非常短，但我们预计 Node.js、Python 和二进制三种扩展都会包含如下文件：[60]

{
  "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 规范 提供了大量便捷选项，便于配置与安装本地 MCP server。server 配置可支持模板变量与平台覆盖，让扩展开发者精确声明需要的用户配置。[60]

例如以下 manifest 要求用户提供 api_key，Claude 会在用户填写前不启用扩展，并把密钥安全存入系统秘钥库，在启动时用 ${user_config.api_key} 自动替换： [60]

{
  "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 可能长这样：[60]

{
  "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-mcp-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 规范文档。[60]

构建第一个扩展

以文件系统 MCP server 为例，打包流程如下：[60]

步骤 1：创建 manifest

npx @anthropic-ai/mcpb init

该交互式工具会生成完整 manifest.json。若想快速得到最小版本，可加 --yes。[60]

步骤 2：声明用户配置

如果需要用户输入（如 API key、可访问目录），在 manifest 声明：[60]

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

Claude Desktop 会：[60]

  • 展示友好的配置 UI
  • 在启用前校验输入
  • 安全存储敏感值
  • 以参数或环境变量方式传给 server

例如用环境变量传入配置：[60]

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

npx @anthropic-ai/mcpb pack

该命令会：[60]

  1. 校验 manifest
  2. 生成 .mcpb 包

步骤 4：本地测试

把 .mcpb 拖进 Claude Desktop 设置页，你会看到：[60]

  • 可读的扩展信息
  • 需要的权限与配置
  • 简洁的 “Install” 按钮

高级特性

跨平台支持

扩展可以针对 OS 覆盖配置：[60]

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

动态配置

可用模板变量： [60]

  • ${__dirname}：扩展安装目录
  • ${user_config.key}：用户配置
  • ${HOME}、${TEMP}：系统环境变量

功能声明

提前说明扩展能力：[60]

"tools": [
  {
    "name": "read_file",
    "description": "Read contents of a file"
  }
],
"prompts": [
  {
    "name": "code_review",
    "description": "Review code for best practices",
    "arguments": ["file_path"]
  }
]

扩展目录（Extension Directory）

Claude Desktop 将提供内置扩展目录，用户可浏览、搜索并一键安装，无需在 GitHub 中筛选。[60]

我们预计 Desktop Extension 规范与 Claude 的实现会持续演进，期待看到扩展如何在创意上拓展 Claude 的能力。[60]

提交扩展步骤：[60]

  1. 按提交表单的指南准备
  2. 在 Windows 与 macOS 上测试
  3. 提交扩展
  4. 团队审核质量与安全

构建开放生态

我们致力于 MCP server 的开放生态，并将 Desktop Extension 规范、工具链以及 Claude（macOS/Windows）实现所需的 schema 与关键函数开源。希望 MCPB 不仅让本地 MCP server 更便携，也能服务其他 AI 桌面应用。[60]

开源内容包括：[60]

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

这意味着：[60]

  • MCP server 开发者：一次打包，所有支持 MCPB 的应用可用
  • 应用开发者：无需从零构建即可支持扩展
  • 用户：MCP 生态应用体验一致

规范与工具链采用 0.1 版本号，期待与社区共同迭代。[60]

安全与企业考虑

扩展引入新的安全挑战，我们在预览版中内置多项防护：[60]

面向用户

  • 敏感数据存入系统 keychain
  • 自动更新
  • 可审计已安装扩展

面向企业

  • Windows 的 Group Policy 与 macOS 的 MDM 支持
  • 预装已批准扩展
  • 支持 publisher/extension blocklist
  • 可关闭扩展目录
  • 部署私有扩展目录

更多企业管理信息见 官方文档。[60]

开始使用

MCP server 开发者：阅读 开发文档，或直接在 MCP server 目录运行：[60]

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

Claude Desktop 用户：升级到最新版本，在设置页找到 Extensions。

企业：阅读企业部署文档。[60]

用 Claude Code 构建扩展

在 Anthropic 内部，我们发现 Claude 很擅长构建扩展，只需少量提示。我们建议把以下内容加入提示词：[60]

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 交到更多人手里。[60]

在 Anthropic 内部，我们用扩展分享高度实验性的 MCP server——有些有趣、有些实用。例如，我们曾把 PyBoy GameBoy 模拟器打包成扩展，让 Claude 直接控制 GameBoy，类似我们的 “Claude plays Pokémon” 研究。我们相信还有无数机会把模型能力连接到用户本地的数据与应用。[60]

我们迫不及待想看到你构建的扩展。从数千 MCP server 到面向数百万用户，只需一键。准备好分享你的 MCP server？提交扩展审核。[60]

图：原文未提供图注

图注：原文未提供图注。[60]

想进一步学习？Explore courses