发布 MCP 服务器

将您的 MCP 服务器发布到官方 Registry 的完整指南。

给 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。

学习目标

完成本教程后，您将能够：

为您的 MCP 服务器创建 server.json 文件
通过 Registry 进行身份验证
成功发布您的服务器
验证您的服务器出现在 Registry 中

前提条件

您已经构建的 MCP 服务器（如果还没有，请按此指南操作）

部署选项概览

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

📦 包部署

发布到注册中心（npm、PyPI、NuGet、Docker Hub 等）并由客户端本地运行。

🌐 远程部署

作为 Web 服务托管，客户端直接连接。

🔄 混合部署

同时提供包和远程选项，实现最大灵活性。

了解更多关于 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+：

# 克隆 registry 仓库
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
# 将 mcp-publisher.exe 移动到您的 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": "您的 MCP 服务器描述",
  "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 包

要求

在您的 package.json 中添加 mcpName 字段：

{
  "name": "your-npm-package",
  "version": "1.0.0",
  "mcpName": "io.github.username/server-name"
}

工作原理

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

server.json 示例

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

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

PyPI 包

要求

在您的包 README 文件中包含服务器名称，使用此格式：

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

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

工作原理

Registry 获取 https://pypi.org/pypi/your-package/json
如果 README 内容中有 mcp-name: server-name 则通过

server.json 示例

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

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

NuGet 包

要求

在您的包的 README 中包含服务器名称，使用此格式：

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

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

工作原理

Registry 从 https://api.nuget.org/v3-flatcontainer/{id}/{version}/readme 获取 README
如果在 README 内容中找到 mcp-name: server-name 则通过

server.json 示例

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

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

Docker/OCI 镜像

要求

向您的 Docker 镜像添加注释：

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

工作原理

Registry 使用基于令牌的身份验证与容器注册中心进行身份验证
使用 Docker Registry v2 API 获取镜像清单
检查 io.modelcontextprotocol.server.name 注释是否匹配您的服务器名称
如果注释缺失或不匹配则失败

server.json 示例（Docker Hub）

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

server.json 示例（GitHub Container Registry）

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

官方 MCP Registry 目前支持 Docker Hub（https://docker.io）和 GitHub Container Registry（https://ghcr.io）。

MCPB 包

要求

MCP 引用 - MCPB 包 URL 必须在其中包含"mcp"，以确保上传了正确的工件。这可能是 .mcpb 扩展名或仓库名称中。

文件完整性 - MCPB 包必须包含 SHA-256 哈希以进行文件完整性验证。这在发布时是必需的，MCP 客户端将在安装前验证此哈希。

如何生成文件哈希

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

openssl dgst -sha256 server.mcpb

server.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 客户端在安装包之前验证哈希以确保文件完整性
官方注册中心存储哈希但不验证它们
子注册中心可能选择实施自己的验证

官方 MCP Registry 目前仅支持托管在 GitHub 或 GitLab releases 上的工件。

远程部署配置

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

远程服务器配置

要求

服务端点：您的 MCP 服务器必须在指定 URL 可访问
传输协议：从 sse（服务器发送事件）或 streamable-http 中选择
URL 验证：仅限域名命名空间（请参阅下面的 URL 要求）

server.json 示例

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "com.yourcompany/api-server",
  "description": "云托管的 API 操作 MCP 服务器",
  "version": "2.0.0",
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse"
    }
  ]
}

URL 验证要求

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

步骤 4：身份验证

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

GitHub 身份验证（用于 io.github.* 命名空间）

mcp-publisher login github

这将打开您的浏览器进行 OAuth 身份验证。

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

# 生成密钥对
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

您将看到类似输出：

✓ 发布成功

步骤 6：验证发布

通过搜索您的服务器来检查它是否出现在注册中心中：

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

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

故障排除

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

“身份验证失败” - 验证您已正确设置 DNS 记录或登录到正确的 GitHub 账户。

“命名空间未授权” - 您的身份验证方法不匹配您选择的命名空间格式。

示例

查看这些已发布服务器的真实示例：

下一步

发布带有更新 server.json 文件的新版本使用 GitHub Actions 自动化发布深入理解 server.json 格式查看远程服务器配置和混合部署

完成了什么

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

🎉 恭喜！ 您的 MCP 服务器现已在官方 Registry 中可用！