modelcontextprotocol/registry · 上手攻略

仓库：modelcontextprotocol/registry
链接：https://github.com/modelcontextprotocol/registry
分类：mcp · developer-tools
作者：Tom
更新：2026-09-06

是什么

MCP Registry 是 Model Context Protocol（MCP）服务器的社区驱动型注册服务平台，定位为「MCP 服务器的 App Store」——MCP 客户端从这里发现、查询和接入各类 MCP 服务器。

MCP（Model Context Protocol）是 Anthropic 主导的上下文协议，用于标准化 AI 助手与外部工具/数据源的连接。Registry 则是 MCP 生态的包分发基础设施，由 Model Context Protocol Working Group 维护，2025-09-08 以预览版发布。

⚠️ 版本状态：当前为预览版（Preview），API 处于 v0.1 冻结期（承诺稳定至少一个月），正式 GA 版本后将进入 v1.0。

解决什么问题

在 MCP 生态中，开发者需要一个统一的发现、分发与认证机制：

发现：开发者找不到有哪些可用的 MCP 服务器，Registry 提供可查询的服务器目录
分发：MCP 服务器开发者需要一个标准渠道发布自己的作品，Registry 提供 CLI 发布工具
认证：Namespace 归属验证——防止他人冒用你的域名或 GitHub 用户名发布包

核心 API 地址：https://registry.modelcontextprotocol.io

快速安装

方式一：本地 Docker 开发环境（推荐）

# 克隆仓库
git clone https://github.com/modelcontextprotocol/registry.git
cd registry

# 启动完整开发环境（PostgreSQL + Registry，自动构建 ko 镜像）
make dev-compose

# 访问本地 Registry
# → http://localhost:8080
# 数据库为临时存储，重启容器数据清空

离线开发时从文件加载种子数据：

MCP_REGISTRY_SEED_FROM=data/seed.json \
MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION=false \
make dev-compose

方式二：直接运行 Docker 镜像（无需构建）

⚠️ 镜像不自带 PostgreSQL，需自备数据库。

# 启动 PostgreSQL（示例）
docker run -d --name mcp-postgres \
  -e POSTGRES_DB=mcp_registry \
  -e POSTGRES_USER=registry \
  -e POSTGRES_PASSWORD=secret \
  postgres:16

# 启动 Registry 并连接 PostgreSQL
docker run -p 8080:8080 \
  -e MCP_REGISTRY_DATABASE_URL="postgresql://registry:secret@host.docker.internal:5432/mcp_registry" \
  ghcr.io/modelcontextprotocol/registry:latest

可用镜像标签： - latest / v1.x.x —— 最新稳定 release - main —— main 分支最新构建 - main-YYYYMMDD-xxx —— 特定提交的开发构建

发布自己的 MCP 服务器

# 构建发布 CLI
make publisher

# 查看帮助
./bin/mcp-publisher --help

详细发布流程请参阅 Publisher Quickstart。

核心用法

查询 MCP 服务器

Registry API 文档（Live）：https://registry.modelcontextprotocol.io/docs

典型 API 端点（推测结构，⚠️ v0.1 冻结期，具体以官方文档为准）：

GET /v0/servers              # 列出所有服务器
GET /v0/servers/{namespace} # 按命名空间查询
GET /v0/servers/{namespace}/{name}  # 特定服务器详情

Namespace 体系

Registry 使用命名空间组织服务器，类似于 NPM 的 scope：

Namespace 格式	认证方式
`io.github/{username}`	GitHub OAuth（登录 username 的 GitHub 账号）或 GitHub Action（在 username 的仓库中运行）
`{domain}`	DNS 验证（证明你拥有该域名）
`me.{domain}`	HTTP 验证（证明你控制该域名的 Web 服务）

示例： - 发布 io.github/domdomegg/my-cool-mcp → 必须以 GitHub 用户 domdomegg 身份登录，或在 domdomegg 名下的 GitHub Action 中发布 - 发布 me.adamjones/my-cool-mcp → 需通过 DNS 或 HTTP 验证域名所有权

认证方式

GitHub OAuth —— 浏览器登录 GitHub 授权，适合手动发布
GitHub OIDC —— 适合 CI/CD 自动化发布（GitHub Action 中使用）
DNS 验证 —— 适合拥有域名且通过 DNS 控制权证明的场景
HTTP 验证 —— 适合暂时无法修改 DNS 但有 Web 服务控制权的场景

目录结构（开发者需知）

cmd/
  publisher/          # 发布 CLI 工具
  registry/          # Registry API 服务端
pkg/
  api/v0/            # v0 API 类型定义
  model/             # server.json 数据模型
internal/
  api/               # HTTP handlers
  auth/              # 认证（GitHub OAuth/JWT/namespace blocking）
  database/          # PostgreSQL 持久化
  validators/        # 输入验证

典型适用场景

场景	推荐度	说明
发现并接入社区 MCP 服务器	⭐⭐⭐⭐	相当于 MCP 的 npm search
发布自己的 MCP 服务器	⭐⭐⭐⭐	有完整 CLI 和认证流程
本地开发 MCP Server	⭐⭐⭐	dev-compose 提供完整的本地测试环境
生产环境自建 MCP Registry	⭐⭐	需要 Pulumi 部署配置（deploy/ 目录），适合企业内网场景

坑与注意

预览版稳定性：当前为预览版，breaking changes 或数据重置可能发生，不建议直接用于生产环境。API freeze 仅覆盖 v0.1，v1 仍可 breaking。
PostgreSQL 必需：Docker 镜像不捆绑数据库，必须自备 PostgreSQL（最低 PostgreSQL 14，官方示例用 postgres:16）。
ko 构建依赖：本地 dev-compose 使用 ko 构建 Go 镜像，首次运行会自动下载大量依赖和网络带宽。
Namespace 冲突：Registry 会在发布时验证 namespace 归属，如果域名或 GitHub 用户名已被占用则无法发布同名包。
种子数据筛选：dev-compose 默认从生产 API 拉取筛选后的种子数据子集，保证本地与生产行为一致；离线开发可切换到本地 seed.json。
ghcr.io 镜像拉取：国内环境可能需要配置 Docker 镜像加速，否则首次拉取 ghcr.io 镜像可能较慢。

与同类对比

特性	MCP Registry	NPM Registry	Docker Hub
定位	MCP 服务器包分发	NPM 包分发	容器镜像分发
认证	GitHub OAuth/OIDC + DNS	NPM 账号	Docker 账号
协议	REST API (v0.1)	Registry API	Registry API v2
所有权验证	Namespace 归属验证	NPM 账号名	Namespace 验证
状态	预览版	成熟稳定	成熟稳定
维护方	MCP Working Group	npm, Inc.	Docker, Inc.

核心差异：MCP Registry 是 MCP 生态特有的分发基础设施，Namespace 归属验证（GitHub/DNS）设计借鉴了 Let's Encrypt 和 CERTIFICATE 验证思路，比 NPM 的账号体系更轻量。

一句话推荐结论

如果你在构建 MCP 生态工具或 AI 应用，MCP Registry 是必须了解的底层组件——它不只是"找服务器"的地方，更是理解 MCP 生态包分发机制和 namespace 认证的最佳实践样本；发布自己的 MCP 服务器前，建议先在本地 dev-compose 完整走一遍发布流程。