MCP注册表（2025-09-08）————发布您的MCP服务器

翻译自：https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/publish-server.md

将MCP服务器发布到注册表的完整指南。

[!提示] 使用一个有主动性的 AI 编码助手？只需使用以下提示：

阅读 https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/guides/publishing/publish-server.md 和 https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/guides/publishing/github-actions.md。评估将此服务器发布到注册表的最佳方法（尽可能优先选择自动的CI流程，而非手动流程），并实施它。如果可能，在告诉用户完成之前，使用适当的 JSON 模式库或用户计算机上可用的工具，根据 $schema 验证 server.json。如果遇到困难，引导用户完成发布过程中他们需要执行的部分（例如，如果是手动发布，需要登录 publisher CLI 时）。

你将学习的内容

在本教程结束时，您将完成以下内容：

• 为您的MCP服务器创建一个server.json文件
• 使用注册表进行身份验证
• 成功发布您的服务器
• 验证您的服务器出现在注册表中

先决条件

• 一个你已经构建的MCP服务器（如果你还没有，可以按照此指南操作）。

部署选项

您可以通过多种方式使您的MCP服务器可用：

• 📦 软件包部署：发布到注册表（如 npm、PyPI、Docker Hub 等）并由客户端本地运行
• 🌐 远程部署：作为网络服务托管，客户端可直接连接
• 🔄 混合部署：提供打包和远程选项以实现最大灵活性

在官方文档中了解更多关于MCP服务器架构的信息。

第1步：安装Publisher CLI

🍺 macOS/Linux/WSL: 使用 Homebrew（推荐）

需要Homebrew:

brew install mcp-publisher

⬇️ macOS/Linux/WSL：预构建二进制文件

curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

🏗️ macOS/Linux/WSL: 从源码构建

需要 Git、Make 和 Go 1.24+：

# 克隆注册表仓库
git clone https://github.com/modelcontextprotocol/registry
cd registry
make publisher

# 二进制文件将位于bin/mcp-publisher
export PATH=$PATH:$(pwd)/bin

🪟 Windows PowerShell：预先构建的二进制文件

$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz
# Move mcp-publisher.exe to a directory in your PATH

步骤 2：初始化您的 server.json

导航到您的服务器目录并创建一个模板：

cd /path/to/your/mcp-server
mcp-publisher init

这会创建一个带有自动检测值的 server.json。你会看到类似以下的内容：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.github.yourname/your-server",
  "description": "A description of your MCP server",
  "version": "1.0.0",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "your-package-name",
      "version": "1.0.0"
    }
  ]
}

步骤3：配置您的服务器详细信息

编辑生成的server.json：

选择你的命名空间

name 字段决定了认证需求：

• io.github.yourname/* - 需要 GitHub 认证
• com.yourcompany/* - 需要进行DNS或HTTP域名验证

配置部署方法

将您的服务器配置为支持软件包、远程或两者兼有。

包部署

添加包验证元数据以证明您对包的所有权。

📦 NPM Packages

要求

在你的 package.json 文件中添加一个 mcpName 字段：

{
  "name": "你的npm包",
  "version": "1.0.0",
  "mcpName": "io.github.username/服务器名字"
}

它是如何工作的

• 注册表获取 `https://registry.npmjs.org/your-npm-package
• 检查 mcpName 字段是否与您的服务器名称匹配。
• 如果字段缺失或不匹配则失败

示例服务器.json

{
  "name": "io.github.username/server-name",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "your-npm-package",
      "version": "1.0.0"
    }
  ]
}

官方的MCP注册表目前仅支持NPM公共注册表（https://registry.npmjs.org）。

🐍 PyPI 软件包

要求

将您的服务器名称以此格式包含在您的包README文件中：

MCP名称格式：mcp-name: io.github.username/server-name

将其添加到您的README.md文件中（它会成为PyPI上的软件包描述）。如果您想在其他地方隐藏它，可以将其放在注释中。

它是如何工作的

• 注册表获取 https://pypi.org/pypi/your-package/json
• 如果 mcp-name: server-name 在 README 内容中，则通过。

示例服务器.json

{
  "name": "io.github.username/server-name",
  "packages": [
    {
      "registry_type": "pypi",
      "identifier": "your-pypi-package",
      "version": "1.0.0"
    }
  ]
}

官方的MCP注册表目前仅支持官方的PyPI注册表（https://pypi.org）。

📋 NuGet 包

要求

在你的软件包的README文件中使用以下格式包含你的服务器名称：

MCP名称格式：mcp-name: io.github.username/server-name

将一个包含服务器名称的README文件添加到你的NuGet包中。如果你想在其他地方隐藏它，可以将其放在注释中。

它是如何工作的

• 注册表从 https://api.nuget.org/v3-flatcontainer/{id}/{version}/readme 获取自述文件。
• 如果在README内容中找到mcp-name: server-name，则通过。

示例服务器.json

{
  "name": "io.github.username/server-name",
  "packages": [
    {
      "registry_type": "nuget",
      "identifier": "Your.NuGet.Package",
      "version": "1.0.0"
    }
  ]
}

官方的MCP注册表目前仅支持官方的NuGet注册表（https://api.nuget.org）。

🐳 Docker/OCI 镜像

要求

为您的 Docker 镜像添加一个注释：

LABEL io.modelcontextprotocol.server.name="io.github.username/server-name"

它是如何工作的

• 注册表使用公共令牌与Docker Hub进行身份验证。
• 使用 Docker Registry v2 API 获取镜像清单
• 检查 io.modelcontextprotocol.server.name 注解是否与您的服务器名称匹配。
• 如果注释缺失或不匹配，则失败

示例服务器.json

{
  "name": "io.github.username/server-name", 
  "packages": [
    {
      "registry_type": "oci",
      "identifier": "yourusername/your-mcp-server",
      "version": "1.0.0"
    }
  ]
}

标识符是 namespace/repository，版本是标签，并可以选择性地包括摘要。

官方的MCP注册表目前仅支持官方的Docker注册表（https://docker.io）。

📁 MCPB Packages

要求

MCP参考 - MCPB软件包的URL必须在某处包含“mcp”，以确保上传了正确的工件。这可以通过.mcpb扩展名或在您的存储库名称中实现。

文件完整性 - MCPB 包必须包含用于文件完整性验证的 SHA-256 哈希值。此操作是在发布时必需的，MCP 客户端将在安装前验证该哈希值。

如何生成文件哈希

计算你的MCPB文件的SHA-256哈希值：

openssl dgst -sha256 server.mcpb

示例服务器.json

{
  "name": "io.github.username/server-name",
  "packages": [
    {
      "registry_type": "mcpb",
      "identifier": "https://github.com/you/your-repo/releases/download/v1.0.0/server.mcpb",
      "file_sha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce"
    }
  ]
}

文件哈希验证

• 作者 负责在创建 server.json 时生成正确的 SHA-256 哈希值。
• MCP 客户端 在安装软件包之前验证哈希值以确保文件完整性。
• 官方注册表存储哈希但不验证它们。
• 子注册处可以选择实施自己的验证。这使他们能够对MCPB文件进行安全扫描，并确保客户端获得相同的经过安全扫描的内容。

官方的MCP注册表目前仅支持托管在GitHub或GitLab版本上的工件。

远程部署

将 remotes 字段添加到您的 server.json 中（可以与 packages 共存）：

🌐 远程服务器配置

要求

• 服务端点：您的MCP服务器必须可以通过指定的URL访问。
• 传输协议：选择 sse（服务器发送事件）或 streamable-http
• URL验证：仅适用于域命名空间（请参阅以下URL要求）

示例服务器.json

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "com.yourcompany/api-server",
  "description": "Cloud-hosted MCP server for API operations",
  "version": "2.0.0",
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse"
    }
  ]
}

多种交通选项

你可以提供多种连接方式：

{
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse"
    },
    {
      "type": "streamable-http", 
      "url": "https://mcp.yourcompany.com/http"
    }
  ]
}

URL验证要求

• 对于 com.yourcompany/* 命名空间：URL 必须位于 yourcompany.com 或其子域名。
• 对于io.github.username/*命名空间：没有URL限制（但您必须通过GitHub进行身份验证）。

身份验证标头（可选）

配置客户端连接时应发送的请求头。

{
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse",
      "headers": [
        {
          "name": "X-API-Key", 
          "description": "API key for authentication",
          "is_required": true,
          "is_secret": true
        }
      ]
    }
  ]
}

步骤 4：身份验证

根据您的命名空间选择身份验证方法。

GitHub认证（用于io.github.*命名空间）

mcp-publisher login github

这会打开你的浏览器进行OAuth认证。

DNS验证（用于自定义域名）

bash
# 生成密钥对
openssl genpkey -algorithm Ed25519 -out key.pem

# 获取用于DNS记录的公钥
echo "yourcompany.com. IN TXT \"v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""

# 将TXT记录添加到你的DNS中，然后登录
mcp-publisher login dns --domain yourcompany.com --private-key $(openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')

第5步：发布你的服务器

认证完成后，发布您的服务器：

mcp-publisher publish

你将看到类似这样的输出：

✓ Successfully published

步骤6：验证出版物

检查您的服务器是否出现在注册表中，可以通过搜索进行验证：

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.yourname/weather-server"

您应该会在 JSON 响应中看到您的服务器元数据。

故障排除

"包验证失败" - 请确保您的包中包含所需的验证元数据（mcpName字段、README提及或Docker标签）。

"身份验证失败" - 请验证您是否正确设置了DNS记录或已登录到正确的GitHub账户。'''

"命名空间未授权" - 您的身份验证方法与所选的命名空间格式不匹配。

例子

请看这些已发布服务器的实际例子：

• NPM、Docker 和 MCPB 示例
• NuGet 示例
• PyPI 示例

下一步

• 更新你的服务器：使用更新的server.json文件发布新版本
• 设置CI/CD：使用GitHub Actions自动化发布
• 了解更多：深入理解server.json 格式
• 更多示例：请参阅架构文档中的远程服务器配置和混合部署。

你所完成的事情

您已成功将您的第一个MCP服务器发布到注册表！您的服务器现在可以被MCP客户端发现，并且可以被全球用户安装。