快速上手：将 MCP 服务器发布到 MCP 注册表

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

本教程将向你展示如何使用官方 mcp-publisher CLI 工具，把一个用 TypeScript 编写的 MCP 服务器发布到 MCP 注册表。

前置条件

Node.js —— 本教程假定 MCP 服务器是用 TypeScript 编写的。
npm 账户 —— MCP 注册表只托管元数据，不托管制品。在发布到 MCP 注册表之前，我们会先将 MCP 服务器的软件包发布到 npm，因此你需要一个 npm 账户。
GitHub 账户 —— MCP 注册表支持多种认证方法。为简单起见，本教程将使用基于 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 以反映你的信息：

package.json

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

package.json

   "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 注册表会验证服务器的底层软件包与其元数据相匹配。对于 npm 软件包，这需要向 package.json 添加一个 mcpName 属性：

package.json

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

mcpName 的值将成为你的服务器在 MCP 注册表中的名称。由于我们将使用基于 GitHub 的认证，mcpName 必须以 io.github.my-username/ 开头。

第 2 步：发布软件包

MCP 注册表只托管元数据，不托管制品，因此在把服务器发布到 MCP 注册表之前，我们必须先将软件包发布到 npm。确保分发文件已构建：

# 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 工具：

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/

$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

brew install mcp-publisher

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

mcp-publisher --help

你应当看到类似下面的输出：

Output

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 文件，你应当看到类似下面的内容：

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

按需编辑内容：

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",
+  "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 属性必须与 package.json 中的 mcpName 属性匹配。

第 5 步：向 MCP 注册表认证

在本教程中，我们将使用基于 GitHub 的认证向 MCP 注册表认证。运行 mcp-publisher login 命令以发起认证：

mcp-publisher login github

你应当看到类似下面的输出：

Output

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）。完成后，回到终端，你应当看到类似下面的输出：

Output

Successfully authenticated!
✓ Successfully logged in

第 6 步：发布到 MCP 注册表

最后，使用 mcp-publisher publish 命令将你的服务器发布到 MCP 注册表：

mcp-publisher publish

你应当看到类似下面的输出：

Output

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 中看到你服务器的元数据：

Output

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

故障排查

错误消息	处理方法
”Registry validation failed for package”	确保你的软件包包含所需的验证信息（例如 `package.json` 中的 `mcpName` 属性）。
“Invalid or expired Registry JWT token”	通过运行 `mcp-publisher login github` 重新认证。
“You do not have permission to publish this server”	你的认证方法与你服务器的命名空间格式不匹配。使用 GitHub 认证时，你的服务器名称必须以 `io.github.your-username/` 开头。

后续步骤

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

​前置条件

​第 1 步：为软件包添加验证信息

​第 2 步：发布软件包

​第 3 步：安装 mcp-publisher

​第 4 步：创建 server.json

​第 5 步：向 MCP 注册表认证

​第 6 步：发布到 MCP 注册表

​故障排查

​后续步骤

前置条件

第 1 步：为软件包添加验证信息

第 2 步：发布软件包

第 3 步：安装 `mcp-publisher`

第 4 步：创建 `server.json`

第 5 步：向 MCP 注册表认证

第 6 步：发布到 MCP 注册表

故障排查

后续步骤