AI导哈

MCP注册服务器

一个动态的MCP注册服务器，聚合来自多个来源的MCP服务器，支持使用Podman进行按需发现和激活。

  • by tsoernes
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 tsoernes/mcp-registry

使用说明

mcp注册表

一个动态MCP（模型上下文协议）注册服务器，它聚合了来自多个来源的MCP服务器，并使用Podman实现了按需发现和激活。

概述

mcp-registry 是一个基于FastMCP的服务器，它提供了一个统一的接口，用于从多个来源发现、搜索和动态激活MCP服务器：

  • Docker MCP注册表：Docker MCP官方目录(https://github.com/docker/mcp-registry)
  • mcpservers.org：社区策划的MCP服务器，具有丰富的元数据（官方、特色、类别）
  • 未来来源：增加登记册的可扩展架构

与使用Docker容器的Docker动态MCP不同， mcp-registry 用途 波德曼 对于容器化的MCP服务器，使其成为无根容器环境和基于Fedora的系统的理想选择。服务器功能 动态刀具曝光，自动将容器化MCP服务器中发现的工具注册为可调用函数。

特性

核心能力

  • 多源聚合：跨Docker注册表、mcpservers.org等进行统一搜索
  • 模糊搜索：使用智能匹配按名称、描述、标签或类别查找服务器
  • 人气排名：按相关性+受欢迎程度（官方、特色、类别）排序的搜索结果
  • 动态激活：在会话期间按需添加/删除MCP服务器
  • 动态工具曝光：发现的工具自动注册为可调用的MCP函数
  • 实时通知：自动 notifications/tools/list_changed 添加/删除工具时发送给客户端
  • 波德曼集成：使用Podman运行容器化MCP服务器（无根兼容）
  • 类型安全工具调用：动态注册工具的完整类型检查和IDE支持
  • 会话持续：活动服务器在重新启动后仍然存在
  • 自动刷新：来源的背景更新（最多每24小时一次）
  • 元数据：类别、标签、官方/特色标志、API关键要求

注册表工具

服务器向AI代理公开以下工具：

  • mcp_registry_find：按名称、描述、标签或类别搜索MCP服务器（按流行度排序）
  • mcp_registry_list：列出聚合注册表中的所有可用服务器
  • mcp_registry_get_docs：获取MCP服务器的文档和设置说明
  • mcp_registry_launch_stdio：使用自定义命令、参数和环境启动基于stdio的MCP服务器
  • mcp_registry_add：激活MCP服务器（带有动态工具注册的Podman容器）
  • mcp_registry_remove：停用以前添加的服务器
  • mcp_registry_active：列出当前活动/已装载的服务器，包括工具/资源/提示计数
  • mcp_registry_config_set：为服务器配置环境变量
  • mcp_registry_exec：从任何活动服务器执行工具
  • mcp_registry_refresh：强制刷新特定源（遵守速率限制）
  • mcp_registry_status：查看注册表统计信息和运行状况信息

安装

先决条件

  • Python 3.12或更高版本
  • Podman（已安装并可在PATH上访问）
  • Git（用于克隆源代码仓库）

从源代码安装

git clone https://github.com/tsoernes/mcp-registry.git
cd mcp-registry
pip install -e .

使用开发依赖项进行安装

pip install -e ".[dev]"

用法

运行服务器

# Run with FastMCP CLI
fastmcp run mcp_registry_server/server.py

# Or use the installed script
mcp-registry

连接到MCP客户端

克劳德桌面

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "mcp-registry": {
      "command": "mcp-registry",
      "args": []
    }
  }
}

Zed编辑

通过其MCP集成，服务器可以直接在Zed中使用。如果安装在Python环境中，则不需要额外的配置。

其他MCP客户端

任何支持stdio传输的MCP客户端都可以连接到 mcp-registry服务器遵循标准MCP协议。

工作流程示例

一旦连接到MCP客户端（如Claude Desktop或Zed）：

User: "Find MCP servers for working with databases"
→ Agent uses mcp_registry_find to search
→ Returns results sorted by relevance and popularity

User: "Get documentation for the SQLite server"
→ Agent uses mcp_registry_get_docs to show setup instructions

User: "Add the SQLite server"
→ Agent uses mcp_registry_add to activate it (Podman container or stdio process)
→ Tools, resources, and prompts are automatically discovered
→ Discovered tools are registered with dynamic Python functions

User: "List active servers"
→ Agent uses mcp_registry_active
→ Shows server details including tool/resource/prompt counts

User: "Execute a query on the SQLite server"
→ Agent uses mcp_registry_exec with tool_name="sqlite_read_query" 
→ Type-safe tool invocation with JSON Schema validation
→ Results returned from the active MCP server

User: "Remove the SQLite server"
→ Agent uses mcp_registry_remove to deactivate and clean up

建筑

mcp-registry/
├── mcp_registry_server/
│   ├── __init__.py
│   ├── server.py           # FastMCP server instance and tool definitions
│   ├── models.py           # Pydantic models for registry entries
│   ├── registry.py         # Core registry logic and search index
│   ├── sources/            # Git clones of external registries
│   ├── cache/              # JSON metadata cache files
│   ├── scrapers/           # mcpservers.org scraper integration
│   ├── podman_runner.py    # Podman container management
│   └── tasks.py            # Background refresh scheduling
├── tests/                  # pytest test suite
├── scripts/                # Existing mcpservers.org scraper
├── pyproject.toml
├── README.md
└── LICENSE

数据模型

每个注册表项包括：

  • id：稳定确定性段塞
  • name：显示名称
  • description：人类可读的描述
  • source：Origin（docker、mcpservers等）
  • repo_url：源代码库
  • container_image：Docker/Podman镜像参考
  • categories：功能类别
  • tags：可搜索标签
  • official：官方状态（来自mcpservers.org）-提高搜索排名
  • featured：特色状态（来自mcpservers.org）-提高搜索排名
  • requires_api_key：是否需要API证书
  • tools：可用工具名称（激活时发现）
  • resources：可用资源模板（在激活时发现）
  • prompts：可用提示模板（激活时发现）
  • launch_method：如何运行（podman、stdio代理、远程http）
  • server_command：stdio服务器的命令配置（命令、args、env）
  • last_refreshed：上次元数据更新时间戳

搜索排名

搜索结果按以下组合排序：

  • 模糊比赛得分 （60%权重）：查询与服务器名称/描述的匹配程度
  • 人气评分 （40%权重）：基于官方地位、特色地位、类别数量和来源
  • 官方服务器获得+20分
  • 特色服务器获得+10分
  • Docker注册服务器获得+5分
  • 带有容器映像的服务器获得+3分

配置

环境变量

  • MCP_REGISTRY_CACHE_DIR：覆盖缓存目录（默认值： mcp_registry_server/cache)
  • MCP_REGISTRY_SOURCES_DIR：覆盖源目录（默认值： mcp_registry_server/sources)
  • MCP_REGISTRY_REFRESH_INTERVAL：刷新间隔（以小时为单位）（默认值：24）

持久性

活动服务器被持久化 cache/active_mounts.json 并在服务器启动时自动恢复。

性能注意事项

服务器包括定期刷新注册表数据的后台任务。为防止CPU过度使用：

  • 默认情况下，mcpservers.org抓取限制为500台服务器 -整个网站包含5000多台服务器，解析所有HTML文件需要大量的CPU
  • 在后台刷新期间禁用GitHub stars获取 -这减少了HTTP请求并提高了性能
  • 每6小时进行一次刷新检查 -但实际刷新仅在数据超过24小时时发生

如果您遇到CPU使用率高的情况：

  1. 检查后台刷新是否正在运行（日志将显示“正在启动X刷新”）
  2. 安装后的初始刷新比后续刷新处理更多的数据
  3. scraper在可用时使用缓存的HTML来减少网络和解析开销

您可以在中调整这些设置 mcp_registry_server/tasks.py 如果需要的话。

MCP协议支持

工具列表更改通知

服务器实现MCP notifications/tools/list_changed 当可用工具列表更改时，保持客户端更新的协议。在以下情况下会自动发送通知：

  • 添加服务器 (mcp_registry_add)：成功激活Podman容器并注册其工具后
  • 启动stdio服务器 (mcp_registry_launch_stdio)：成功生成流程并注册其工具后
  • 删除服务器 (mcp_registry_remove)：成功删除动态注册的工具后

这允许MCP客户端（如Claude Desktop、Zed或自定义客户端）：

  • 自动更新其工具缓存
  • 刷新可用工具的UI显示
  • 避免轮询工具列表更新

通知使用FastMCP发送 ctx.send_tool_list_changed() 方法在工具执行上下文中，确保它们仅在活动的MCP请求上下文中根据MCP协议规范发送。

备注：在服务器初始化期间或在活动请求上下文之外注册工具时，不会发送通知。

发展

建立开发环境

# Clone the repository
git clone https://github.com/tsoernes/mcp-registry.git
cd mcp-registry

# Install with development dependencies
pip install -e ".[dev]"

运行测试

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_registry.py

# Run specific test
pytest tests/test_models.py::TestRegistryEntry::test_create_valid_entry

跑步覆盖

# Generate coverage report
pytest --cov=mcp_registry_server --cov-report=html

# View coverage in browser
open htmlcov/index.html

代码格式化和linting

# Format code
ruff format .

# Check for issues
ruff check .

# Auto-fix issues
ruff check --fix .

手动测试

# Test the server with fastmcp CLI
fastmcp dev mcp_registry_server/server.py

# Or run directly
python -m mcp_registry_server.server

# Test with an MCP client
# The server uses stdio transport and is designed to be used through
# MCP clients like Claude Desktop or Zed editor

安全考虑

  • 运行前验证容器映像
  • 环境变量注入仅限于allowlist（API_KEY、API_TOKEN、AUTH_、DATABASE_、DB_、GITHUB_、OPENAI_、ANTHROPIC_、AWS_、AZURE_、GCP_、SLACK_、DISCORD_、NOTION_、MCP_）
  • Podman在没有特权访问的情况下运行容器（支持无根模式）
  • 通过验证克隆/提取源存储库
  • 速率限制可防止过多的刷新尝试（刷新之间至少24小时）
  • Stdio服务器在受控环境的隔离进程中运行

路线图

  • [x] 多源聚合框架
  • [x] 波德曼集成
  • [x] 基于RapidFuzz的模糊搜索
  • [x] 会话持久性
  • [x] 后台刷新调度程序
  • [x] 带pytest的全面测试套件
  • [x] 注册表工具（mcp_register_find、mcp_reregistry_list、mcp\/register_get-docs、mcp_legister_launch_strio、mcp\.register_add、mcp_rigister_remove、mcp\-register_active、mcp_Registry_status、mcp_ register_config set、mcp_re register_exec、mcp_inegistry _refresh）
  • [x] Stdio服务器支持自定义启动命令
  • [x] Zed和Claude桌面集成
  • [x] 动态工具发现和注册
  • [x] 资源和快速发现
  • [x] 工具调度（mcp_register_exec实现）
  • []从源自动构建图像
  • []身份验证/机密管理集成
  • []代码模式工具组合
  • []其他注册表源（Awesome MCP）
  • []用于注册表探索的WebUI
  • []Docker编写示例
  • []CI/CD管道

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 添加新功能的测试
  4. 确保所有测试通过
  5. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 了解详情。

项目状态

当前版本： 0.1.0（早期开发）

  • ✅ 核心注册表和搜索功能完成
  • ✅ mcpservers.org scraper集成
  • ✅ Docker注册表git源代码集成
  • ✅ 基于MCP stdio协议的Podman容器管理
  • ✅ Stdio服务器支持自定义启动命令（register_launch_strio）
  • ✅ 动态工具/资源/快速发现和注册
  • ✅ 通过mcp_registerexec执行工具
  • ✅ Zed和Claude桌面集成
  • ✅ 后台刷新调度程序
  • ✅ 全面的测试套件（覆盖率超过70%）
  • ⏳ 基于源代码的服务器构建（计划中）
  • ⏳ 加强秘密管理（计划中）

致谢

支持

相关 MCP