發佈 MCP 服務器

將您的 MCP 服務器發佈到官方 Registry 的完整指南。

給 AI 編程助手的提示
使用此提示快速發佈：

閱讀 https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/guides/publishing/publish-server.md 和 https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/guides/publishing/github-actions.md。評估發佈此服務器到註冊中心的最佳方式（優先使用自動化 CI 流程而非手動流程），並實施。如果可能，在告訴用戶完成之前，使用適當的 JSON schema 庫或工具驗證 server.json。

學習目標

完成本教程後，您將能夠：

為您的 MCP 服務器創建 server.json 文件
通過 Registry 進行身份驗證
成功發佈您的服務器
驗證您的服務器出現在 Registry 中

前提條件

您已經構建的 MCP 服務器（如果還沒有，請按此指南操作）

部署選項概覽

您可以通過多種方式讓您的 MCP 服務器可用：

📦 包部署

發佈到註冊中心（npm、PyPI、NuGet、Docker Hub 等）並由客戶端本地運行。

🌐 遠程部署

作為 Web 服務託管，客戶端直接連接。

🔄 混合部署

同時提供包和遠程選項，實現最大靈活性。

瞭解更多關於 MCP 服務器架構的信息。

步驟 1：安裝 Publisher CLI

macOS/Linux/WSL：使用 Homebrew（推薦）

需要 Homebrew：

brew install mcp-publisher

macOS/Linux/WSL：預構建二進制

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

macOS/Linux/WSL：從源碼構建

需要 Git、Make 和 Go 1.24+：

# 克隆 registry 倉庫
git clone https://github.com/modelcontextprotocol/registry
cd registry
make publisher

# 二進制文件將位於 bin/mcp-publisher
export PATH=$PATH:$(pwd)/bin

Windows PowerShell：預構建二進制

$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }
Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_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 中的目錄

步驟 2：初始化您的 server.json

導航到您的服務器目錄並創建模板：

cd /path/to/your/mcp-server
mcp-publisher init

這將創建一個包含自動檢測值的 server.json。您將看到類似內容：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.github.yourname/your-server",
  "description": "您的 MCP 服務器描述",
  "version": "1.0.0",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "your-package-name",
      "version": "1.0.0"
    }
  ]
}

步驟 3：配置服務器詳情

編輯生成的 server.json：

選擇命名空間

name 字段決定身份驗證要求：

io.github.yourname/* - 需要 GitHub 身份驗證
com.yourcompany/* - 需要 DNS 或 HTTP 域名驗證

配置部署方式

配置您的服務器以支持包、遠程或兩者：

包部署配置

為證明包所有權，添加包驗證元數據。

NPM 包

要求

在您的 package.json 中添加 mcpName 字段：

{
  "name": "your-npm-package",
  "version": "1.0.0",
  "mcpName": "io.github.username/server-name"
}

工作原理

Registry 獲取 https://registry.npmjs.org/your-npm-package
檢查 mcpName 字段是否匹配您的服務器名稱
如果字段缺失或不匹配則失敗

server.json 示例

{
  "name": "io.github.username/server-name",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "your-npm-package",
      "version": "1.0.0"
    }
  ]
}

官方 MCP Registry 目前僅支持 NPM 公共註冊中心（https://registry.npmjs.org）。

PyPI 包

要求

在您的包 README 文件中包含服務器名稱，使用此格式：

MCP 名稱格式：mcp-name: io.github.username/server-name

將其添加到您的 README.md 文件（在 PyPI 上成為包描述）。如果您想在其他地方隱藏它，可以放在註釋中。

工作原理

Registry 獲取 https://pypi.org/pypi/your-package/json
如果 README 內容中有 mcp-name: server-name 則通過

server.json 示例

{
  "name": "io.github.username/server-name",
  "packages": [
    {
      "registry_type": "pypi",
      "identifier": "your-pypi-package",
      "version": "1.0.0"
    }
  ]
}

官方 MCP Registry 目前僅支持官方 PyPI 註冊中心（https://pypi.org）。

NuGet 包

要求

在您的包的 README 中包含服務器名稱，使用此格式：

MCP 名稱格式：mcp-name: io.github.username/server-name

向您的 NuGet 包添加包含服務器名稱的 README 文件。如果您想在其他地方隱藏它，可以放在註釋中。

工作原理

Registry 從 https://api.nuget.org/v3-flatcontainer/{id}/{version}/readme 獲取 README
如果在 README 內容中找到 mcp-name: server-name 則通過

server.json 示例

{
  "name": "io.github.username/server-name",
  "packages": [
    {
      "registry_type": "nuget",
      "identifier": "Your.NuGet.Package",
      "version": "1.0.0"
    }
  ]
}

官方 MCP Registry 目前僅支持官方 NuGet 註冊中心（https://api.nuget.org）。

Docker/OCI 鏡像

要求

向您的 Docker 鏡像添加註釋：

LABEL io.modelcontextprotocol.server.name="io.github.username/server-name"

工作原理

Registry 使用基於令牌的身份驗證與容器註冊中心進行身份驗證
使用 Docker Registry v2 API 獲取鏡像清單
檢查 io.modelcontextprotocol.server.name 註釋是否匹配您的服務器名稱
如果註釋缺失或不匹配則失敗

server.json 示例（Docker Hub）

{
  "name": "io.github.username/server-name", 
  "packages": [
    {
      "registry_type": "oci",
      "registry_base_url": "https://docker.io",
      "identifier": "yourusername/your-mcp-server",
      "version": "1.0.0"
    }
  ]
}

server.json 示例（GitHub Container Registry）

{
  "name": "io.github.username/server-name", 
  "packages": [
    {
      "registry_type": "oci",
      "registry_base_url": "https://ghcr.io",
      "identifier": "yourusername/your-mcp-server",
      "version": "1.0.0"
    }
  ]
}

官方 MCP Registry 目前支持 Docker Hub（https://docker.io）和 GitHub Container Registry（https://ghcr.io）。

MCPB 包

要求

MCP 引用 - MCPB 包 URL 必須在其中包含"mcp"，以確保上傳了正確的工件。這可能是 .mcpb 擴展名或倉庫名稱中。

文件完整性 - MCPB 包必須包含 SHA-256 哈希以進行文件完整性驗證。這在發佈時是必需的，MCP 客戶端將在安裝前驗證此哈希。

如何生成文件哈希

計算您的 MCPB 文件的 SHA-256 哈希：

openssl dgst -sha256 server.mcpb

server.json 示例

{
  "name": "io.github.username/server-name",
  "packages": [
    {
      "registry_type": "mcpb",
      "identifier": "https://github.com/you/your-repo/releases/download/v1.0.0/server.mcpb",
      "file_sha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce"
    }
  ]
}

文件哈希驗證

作者負責在創建 server.json 時生成正確的 SHA-256 哈希
MCP 客戶端在安裝包之前驗證哈希以確保文件完整性
官方註冊中心存儲哈希但不驗證它們
子註冊中心可能選擇實施自己的驗證

官方 MCP Registry 目前僅支持託管在 GitHub 或 GitLab releases 上的工件。

遠程部署配置

將 remotes 字段添加到您的 server.json（可與 packages 共存）：

遠程服務器配置

要求

服務端點：您的 MCP 服務器必須在指定 URL 可訪問
傳輸協議：從 sse（服務器發送事件）或 streamable-http 中選擇
URL 驗證：僅限域名命名空間（請參閱下面的 URL 要求）

server.json 示例

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "com.yourcompany/api-server",
  "description": "雲託管的 API 操作 MCP 服務器",
  "version": "2.0.0",
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse"
    }
  ]
}

URL 驗證要求

對於 com.yourcompany/* 命名空間：URL 必須在 yourcompany.com 或其子域上
對於 io.github.username/* 命名空間：無 URL 限制（但您必須通過 GitHub 進行身份驗證）

步驟 4：身份驗證

根據您的命名空間選擇身份驗證方法：

GitHub 身份驗證（用於 io.github.* 命名空間）

mcp-publisher login github

這將打開您的瀏覽器進行 OAuth 身份驗證。

DNS 身份驗證（用於自定義域名）

# 生成密鑰對
openssl genpkey -algorithm Ed25519 -out key.pem

# 獲取 DNS 記錄的公鑰
echo "yourcompany.com. IN TXT \"v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""

# 將 TXT 記錄添加到您的 DNS，然後登錄
mcp-publisher login dns --domain yourcompany.com --private-key $(openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')

步驟 5：發佈您的服務器

完成身份驗證後，發佈您的服務器：

mcp-publisher publish

您將看到類似輸出：

✓ 發佈成功

步驟 6：驗證發佈

通過搜索您的服務器來檢查它是否出現在註冊中心中：

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.yourname/weather-server"

您應該在 JSON 響應中看到返回的服務器元數據。

故障排除

“包驗證失敗” - 確保您的包包含所需的驗證元數據（mcpName 字段、README 提及或 Docker 標籤）。

“身份驗證失敗” - 驗證您已正確設置 DNS 記錄或登錄到正確的 GitHub 賬戶。

“命名空間未授權” - 您的身份驗證方法不匹配您選擇的命名空間格式。

示例

查看這些已發佈服務器的真實示例：

下一步

更新您的服務器

發佈帶有更新 server.json 文件的新版本

設置 CI/CD

使用 GitHub Actions 自動化發佈

完成了什麼

您已成功將您的第一個 MCP 服務器發佈到註冊中心！您的服務器現在可被 MCP 客戶端發現，並可被全世界的用戶安裝。

🎉 恭喜！ 您的 MCP 服務器現已在官方 Registry 中可用！