快速入门：将 MCP 服务器发布到 MCP Registry
快速入门：将 MCP 服务器发布到 MCP Registry
社区译文；来源： MCP 80041ab0
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 [email protected]: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 工具：
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 PATHbrew 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 属性必须与 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" ... }]}故障排除
| 错误消息 | 处理方法 |
|---|---|
| “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 自动发布。