把自建 MCP Server 打包成 .mcpb 一键装进 Claude Desktop：manifest、user_config 与分发实操

# 全局安装 MCPB CLI（npm 包名：@anthropic-ai/mcpb）
npm install -g @anthropic-ai/mcpb

# 进入你的 MCP Server 项目目录，初始化
cd my-mcp-server
mcpb init

mcpb init 会以问答方式引导你填好 manifest 的各个字段：包名、版本、描述、作者、Server 类型（node / python / binary / uv）、入口文件、用户安装时要配置的项。填完自动落盘一份 manifest.json 到项目根目录。老项目注意：如果你在远古教程里见过 dxt 命令或 .dxt 文件，那是更名前的旧称，一律换成 mcpb 与 .mcpb。

manifest 的核心是 server.mcp_config——宿主就按它把你的 Server 当 stdio 子进程启动。一份完整的 Node 示例（官方 local-files 示例的骨架）：

{
  "$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
  "manifest_version": "0.4",
  "name": "local-files",
  "version": "0.1.0",
  "description": "Read, search, and watch files on the local filesystem.",
  "author": { "name": "Your Name" },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": { "ROOT_DIR": "${user_config.rootDir}" }
    }
  },
  "user_config": {
    "rootDir": {
      "type": "directory",
      "title": "Root directory",
      "description": "Directory to expose. Defaults to ~/Documents.",
      "default": "${HOME}/Documents",
      "required": true
    }
  },
  "compatibility": {
    "claude_desktop": ">=1.0.0",
    "platforms": ["darwin", "win32", "linux"]
  }
}

三个最容易踩的点：其一，${__dirname} 在安装后被替换为包解压目录，用来拼包内相对路径；其二，${user_config.xxx} 在安装时被替换为用户填的配置值，且没有自动前缀——你的代码读到的环境变量名就是你在 env 里写的名字；其三，v0.4 schema 里所有 server type 都必须有 mcp_config，漏写会导致 mcpb pack 直接失败。

"user_config": {
  "apiToken": {
    "type": "string",
    "title": "API Token",
    "description": "Your service API token.",
    "sensitive": true,
    "required": true
  }
}

凡是 API Key、访问令牌这类凭据，给对应配置项加 "sensitive": true：宿主会把它存进操作系统钥匙串而不是普通配置文件，界面上按密码框渲染。配套地，在 mcp_config.env 里照常声明对应的环境变量映射，Server 代码侧不需要任何改动——读的还是同一个环境变量名。这一步是对「密钥别写进 zip、别写进用户家目录的明文文件」这条军规的官方实现。

# Node 项目：先装生产依赖，把 node_modules 一起打包
npm install --production
mcpb pack

# 产出：my-server.mcpb（当前目录）
# 复现构建建议用锁定文件
npm ci && mcpb pack

Node 是官方推荐的 Server 实现语言，理由很实在：Claude for macOS 与 Windows 自带 Node 运行时，你的包开箱即跑，用户不用额外装任何东西。依赖直接进 node_modules/ 随包分发，用 npm ci 或 yarn install --frozen-lockfile 保证可复现构建。如果依赖里有平台相关的原生编译模块，要在对应平台上分别打包测试，否则换平台可能加载失败。

# 安装方式（任选其一）：
# 1. 双击 .mcpb 文件
# 2. 把 .mcpb 拖进 Claude Desktop 窗口
# 3. Claude Desktop -> Settings -> Extensions
#    -> Advanced settings -> Install Extension
#
# 安装后确认：
# - 用户配置界面按 manifest 的 user_config 渲染
# - sensitive 项进系统钥匙串
# - 会话中 Server 正常拉起、tools/list 返回预期工具

验收时重点看三处：配置界面是否按你的 user_config 定义渲染（特别是 directory 类型的文件夹选择器）；填入敏感项后 Server 能否正常启动并返回工具列表；给一个真实任务跑一遍工具调用。有问题先看 Claude Desktop 的 MCP 日志定位是清单字段问题还是运行时问题。

# 迭代发布：改 manifest 里的 version，重新打包
# （macOS 用 sed / Windows 手改或脚本改均可）
mcpb pack

# 分发渠道：GitHub Release 附件、内网文件服务器、
# 或直接发给同事（一个文件搞定）

MCPB 宿主侧带自动更新能力：用户装过的包在新版本可用时会收到更新提示。发布节奏上建议 manifest 的 version 严格跟随你的语义化版本，同版本号不要重复打包（避免缓存与更新判定混乱）。如果同时想进官方 MCP Registry 做可发现性收录，那是另一条线（server.json + 所有权校验），与本篇的桌面分发互补而非互斥。