> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门：将 MCP 服务器发布到 MCP 注册表

<Note>
  MCP 注册表目前处于预览版。在普遍可用之前，可能会发生破坏性更改或数据重置。如果遇到任何问题，请在 [GitHub](https://github.com/modelcontextprotocol/registry/issues) 上报告。
</Note>

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

## 先决条件

* **Node.js** — 本教程假设 MCP 服务器是用 TypeScript 编写的。
* **npm 账户** — MCP 注册表仅托管元数据，而非制品。在发布到 MCP 注册表之前，我们将把 MCP 服务器的包发布到 npm，因此您需要一个 [npm](https://www.npmjs.com) 账户。
* **GitHub 账户** — MCP 注册表支持 [多种身份验证方法](./authentication)。为简单起见，本教程将使用基于 GitHub 的身份验证，因此您需要一个 [GitHub](https://github.com/) 账户。

如果您没有用 TypeScript 编写的 MCP 服务器，可以从 [`modelcontextprotocol/quickstart-resources` 仓库](https://github.com/modelcontextprotocol/quickstart-resources) 复制 `weather-server-typescript` 服务器以跟随本教程：

```bash theme={null}
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` 以反映您的信息：

```diff package.json theme={null}
 {
-  "name": "mcp-quickstart-ts",
-  "version": "1.0.0",
+  "name": "@my-username/mcp-weather-server",
+  "version": "1.0.1",
   "main": "index.js",
```

```diff package.json theme={null}
   "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` 属性：

```diff package.json theme={null}
 {
   "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。

确保分发生成文件已构建：

```bash theme={null}
# 导航到项目目录
cd weather-server-typescript

# 安装依赖
npm install

# 构建分发生成文件
npm run build
```

然后遵循 npm 的 [发布指南](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages)。特别是，您可能需要运行以下命令：

```bash theme={null}
# 如有必要，验证 npm 身份
npm adduser

# 发布包
npm publish --access public
```

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

## 步骤 3：安装 `mcp-publisher`

使用预构建的二进制文件或 [Homebrew](https://brew.sh) 安装 `mcp-publisher` CLI 工具：

<CodeGroup>
  ```bash macOS/Linux theme={null}
  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/
  ```

  ```powershell Windows theme={null}
  $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
  # 将 mcp-publisher.exe 移动到 PATH 中的目录
  ```

  ```bash theme={null}
  brew install mcp-publisher
  ```
</CodeGroup>

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

```bash theme={null}
mcp-publisher --help
```

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

```text Output theme={null}
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`：

```bash theme={null}
mcp-publisher init
```

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

```json server.json theme={null}
{
  "$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"
        }
      ]
    }
  ]
}
```

根据需要编辑内容：

```diff server.json theme={null}
 {
   "$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` 命令以启动身份验证：

```bash theme={null}
mcp-publisher login github
```

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

```text Output theme={null}
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`）。完成后，返回终端，您应该看到类似以下的输出：

```text Output theme={null}
Successfully authenticated!
✓ Successfully logged in
```

## 步骤 6：发布到 MCP 注册表

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

```bash theme={null}
mcp-publisher publish
```

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

```text Output theme={null}
Publishing to https://registry.modelcontextprotocol.io...
✓ Successfully published
✓ Server io.github.my-username/weather version 1.0.1
```

您可以通过使用 MCP 注册表 API 搜索来验证您的服务器是否已发布：

```bash theme={null}
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.my-username/weather"
```

您应该在搜索结果 JSON 中看到您的服务器元数据：

```text Output theme={null}
{"servers":[{ ... "name":"io.github.my-username/weather" ... }]}
```

## 故障排除

| 错误消息               | 操作                                                                           |
| ------------------ | ---------------------------------------------------------------------------- |
| "包注册表验证失败"         | 确保您的包包含所需的验证信息（例如，`package.json` 中的 `mcpName` 属性）。                           |
| "注册表 JWT 令牌无效或已过期" | 通过运行 `mcp-publisher login github` 重新认证。                                      |
| "您没有权限发布此服务器"      | 您的认证方法与服务器的命名空间格式不匹配。使用 GitHub 认证时，您的服务器名称必须以 `io.github.your-username/` 开头。 |

## 后续步骤

* 了解 [对其他包类型的支持](./package-types)。
* 了解 [对远程服务器的支持](./remote-servers)。
* 了解如何 [使用其他身份验证方法](./authentication)，例如 [DNS 身份验证](./authentication#dns-authentication)，它可为服务器名称前缀启用自定义域。
* 了解如何 [使用 GitHub Actions 自动化发布](./github-actions)。