快速开始：将 MCP 服务端发布到 MCP Registry

NOTE

MCP Registry 目前处于预览阶段。在正式发布之前，可能会出现破坏性变更或数据重置。如果您遇到任何问题，请在 GitHub 上报告。

本教程将向您展示如何使用官方 mcp-publisher CLI 工具，将使用 TypeScript 编写的 MCP 服务端发布到 MCP Registry。

前提条件

• Node.js — 本教程假设 MCP 服务端使用 TypeScript 编写。
• npm 账号 — MCP Registry 仅托管元数据，不托管制品。在发布到 MCP Registry 之前，我们会先将 MCP 服务端的包发布到 npm，因此您需要一个 npm 账号。
• GitHub 账号 — MCP Registry 支持多种身份验证方式。为简单起见，本教程将使用基于 GitHub 的身份验证，因此您需要一个 GitHub 账号。

如果您没有使用 TypeScript 编写的 MCP 服务端，可以从 modelcontextprotocol/quickstart-resources 仓库复制 weather-server-typescript 服务端，以便跟随本教程操作：

git clone --depth 1 git@github.com:modelcontextprotocol/quickstart-resources.git
cp -r quickstart-resources/weather-server-typescript .
rm -rf quickstart-resources
cd weather-server-typescript

并编辑 package.json 以反映您的信息：

 {
-  "name": "mcp-quickstart-ts",
-  "version": "1.0.0",
+  "name": "@my-username/mcp-weather-server",
+  "version": "1.0.1",
   "main": "index.js",

   "license": "ISC",
-  "description": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/my-username/mcp-weather-server.git"
+  },
+  "description": "An MCP server for weather information.",
   "devDependencies": {

步骤 1：向包中添加验证信息

MCP Registry 会验证服务端的底层包与其元数据是否匹配。对于 npm 包，这需要在 package.json 中添加 mcpName 属性：

 {
   "name": "@my-username/mcp-weather-server",
   "version": "1.0.1",
+  "mcpName": "io.github.my-username/weather",
   "main": "index.js",

mcpName 的值将是您的服务端在 MCP Registry 中的名称。

由于我们将使用基于 GitHub 的身份验证，mcpName 必须以 io.github.my-username/ 开头。

步骤 2：发布包

MCP Registry 仅托管元数据，不托管制品，因此我们必须先将包发布到 npm，然后再将服务端发布到 MCP Registry。

确保已构建分发文件：

# Navigate to project directory
cd weather-server-typescript

# Install dependencies
npm install

# Build the distribution files
npm run build

然后遵循 npm 的发布指南。特别是，您可能需要运行以下命令：

# If necessary, authenticate to npm
npm adduser

# Publish the package
npm publish --access public

您可以通过访问包的 npm URL 来验证其是否已发布，例如 https://www.npmjs.com/package/@my-username/mcp-weather-server。

步骤 3：安装 mcp-publisher

使用预构建的二进制文件或 Homebrew 安装 mcp-publisher CLI 工具：

macOS/Linux

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(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/

Windows

$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_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

bash

brew install mcp-publisher

通过运行以下命令验证 mcp-publisher 是否正确安装：

mcp-publisher --help

您应该会看到类似以下的输出：

MCP Registry Publisher Tool

Usage:
  mcp-publisher <command> [arguments]

Commands:
  init          Create a server.json file template
  login         Authenticate with the registry
  logout        Clear saved authentication
  publish       Publish server.json to the registry

步骤 4：创建 server.json

mcp-publisher init 命令可以生成一个 server.json 模板文件，其中包含一些从您的项目派生的信息。

在您的服务端项目目录中，运行 mcp-publisher init：

mcp-publisher init

打开生成的 server.json 文件，您应该会看到类似以下的内容：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.my-username/weather",
  "description": "An MCP server for weather information.",
  "repository": {
    "url": "https://github.com/my-username/mcp-weather-server",
    "source": "github"
  },
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/mcp-weather-server",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      },
      "environmentVariables": [
        {
          "description": "Your API key for the service",
          "isRequired": true,
          "format": "string",
          "isSecret": true,
          "name": "YOUR_API_KEY"
        }
      ]
    }
  ]
}

 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.my-username/weather",
   "description": "An MCP server for weather information.",
   "repository": {
     "url": "https://github.com/my-username/mcp-weather-server",
     "source": "github"
   },
-  "version": "1.0.0",
+  "version": "1.0.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@my-username/mcp-weather-server",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "transport": {
         "type": "stdio"
-      },
-      "environmentVariables": [
-        {
-          "description": "Your API key for the service",
-          "isRequired": true,
-          "format": "string",
-          "isSecret": true,
-          "name": "YOUR_API_KEY"
-        }
-      ]
+      }
     }
   ]
 }

server.json 中的 name 属性 MUST（必须）与 package.json 中的 mcpName 属性一致。

第 5 步：向 MCP Registry 进行身份验证

在本教程中，我们将使用基于 GitHub 的身份验证向 MCP Registry 进行身份验证。

运行 mcp-publisher login 命令以启动身份验证：

mcp-publisher login github

你应该会看到类似以下的输出：

Logging in with github...

To authenticate, please:
1. Go to: https://github.com/login/device
2. Enter code: ABCD-1234
3. Authorize this application
Waiting for authorization...

访问该链接，按照提示操作，并输入终端中打印的授权码（例如上述输出中的 ABCD-1234）。完成后，回到终端，你应该会看到类似以下的输出：

Successfully authenticated!
✓ Successfully logged in

第 6 步：发布到 MCP Registry

最后，使用 mcp-publisher publish 命令将你的服务端发布到 MCP Registry：

mcp-publisher publish

你应该会看到类似以下的输出：

Publishing to https://registry.modelcontextprotocol.io...
✓ Successfully published
✓ Server io.github.my-username/weather version 1.0.1

你可以使用 MCP Registry API 搜索你的服务端，以验证其已发布：

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.my-username/weather"

你应该会在搜索结果 JSON 中看到你的服务端元数据：

{"servers":[{ ... "name":"io.github.my-username/weather" ... }]}

故障排查

Error Message	Action
"Registry validation failed for package"	Ensure your package includes the required validation information (e.g, mcpName property in package.json).
"Invalid or expired Registry JWT token"	Re-authenticate by running mcp-publisher login github.
"You do not have permission to publish this server"	Your authentication method doesn't match your server's namespace format. With GitHub auth, your server name must start with io.github.your-username/.

后续步骤

• 了解对其他包类型的支持。
• 了解对远程服务端的支持。
• 了解如何使用其他身份验证方法，例如 DNS 身份验证，它可为服务端名称前缀启用自定义域名。
• 了解如何使用 GitHub Actions 自动化发布。