> ## Documentation Index > Fetch the complete documentation index at: https://mcp-zh.com/llms.txt > Use this file to discover all available pages before exploring further. # 快速上手：将 MCP 服务器发布到 MCP 注册表 MCP 注册表目前处于预览阶段。在正式发布之前可能发生破坏性变更或数据重置。如果你遇到任何问题，请在 [GitHub](https://github.com/modelcontextprotocol/registry/issues) 上报告。 本教程将向你展示如何使用官方 `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} # Navigate to project directory cd weather-server-typescript # Install dependencies npm install # Build the distribution files npm run build ``` 然后遵循 npm 的[发布指南](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages)。特别地，你可能需要运行以下命令： ```bash theme={null} # 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](https://www.npmjs.com/package/@my-username/mcp-weather-server) ）来验证它已发布。 ## 第 3 步：安装 `mcp-publisher` 使用预构建的二进制文件或 [Homebrew](https://brew.sh) 安装 `mcp-publisher` CLI 工具： ```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 # Move mcp-publisher.exe to a directory in your PATH ``` ```bash theme={null} brew install mcp-publisher ``` 通过运行以下命令验证 `mcp-publisher` 是否已正确安装： ```bash theme={null} mcp-publisher --help ``` 你应当看到类似下面的输出： ```text Output theme={null} MCP Registry Publisher Tool Usage: mcp-publisher [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 Registry 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" ... }]} ``` ## 故障排查 | 错误消息 | 处理方法 | | --------------------------------------------------- | ----------------------------------------------------------------------------- | | "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/` 开头。 | ## 后续步骤 * 了解[对其他软件包类型的支持](./package-types)。 * 了解[对远程服务器的支持](./remote-servers)。 * 了解如何[使用其他认证方法](./authentication)，例如可为服务器名称前缀启用自定义域名的 [DNS 认证](./authentication#dns-authentication)。 * 了解如何[用 GitHub Actions 自动化发布](./github-actions)。