概述
mcp_zoomeye 是一个 Model Context Protocol（MCP）服务器，用于根据查询条件提供网络资产信息。它允许大型语言模型（LLM）通过使用 dork 和其他搜索参数查询 ZoomEye 来获取网络资产信息。该服务器是 ZoomEye MCP Server 的官方开源版本，旨在为 AI 助手和开发环境带来实时网络空间资产情报。
主要能力
- 基于查询条件获取网络资产信息，支持使用 ZoomEye dork 进行查询。
- 提供缓存机制，以提升性能并减少 API 调用（默认缓存 1 小时，可通过 ignore_cache 参数绕过）。
- 对失败的 API 请求提供自动重试机制。
- 提供全面的错误处理与日志记录。
- 搜索范围涵盖设备（IPv4、IPv6）和网站（域名）。搜索字符串在“全局”模式下匹配关键词，包括 HTTP、SSH、FTP 等多种协议的内容（如 HTTP/HTTPS 协议头、正文、SSL、标题及其他协议 banner）。搜索字符串不区分大小写并进行分词匹配；使用 == 时强制执行区分大小写的精确匹配及严格语法。
可用工具
zoomeye_search
根据查询条件获取网络资产信息。
必需参数：
- qbase64（字符串）：Base64 编码的 ZoomEye 搜索查询字符串。
可选参数：
- page（整数）：查看资产页码，默认为 1。
- pagesize（整数）：每页记录数，默认为 10，最大为 1000。
- fields（字符串）：要返回的字段，以逗号分隔。
- sub_type（字符串）：数据类型，支持 v4、v6 和 web，默认 v4。
- facets（字符串）：统计项，多个以逗号分隔。
- ignore_cache（布尔值）：是否忽略缓存。
使用方式
获取 ZoomEye API 密钥
- 访问 https://www.zoomeye.ai
- 注册或登录。
- 点击头像 → Profile。
- 复制 API-KEY。
- 设置环境变量：
export ZOOMEYE_API_KEY="your_api_key_here"
环境要求
- Python 3.10 或更高版本，或者使用 Docker 运行服务器而无需安装 Python。
安装与运行
可通过 pip 安装 mcp-server-zoomeye，安装后以脚本方式运行。也可以使用 Docker 运行 ZoomEye MCP 服务器。项目提供多架构 Docker 镜像，支持 linux/amd64 和 linux/arm64 平台，可在 Intel/AMD 和 ARM（如 Apple Silicon）处理器上运行。也可以从源码构建 Docker 镜像。
使用 uvx 无需特定安装，可直接运行 Python 包；也可以使用 uv 安装包。
环境变量：
- ZOOMEYE_API_KEY：用于身份验证的 ZoomEye API 密钥。
设置方式：
- 在 shell 会话中导出：
export ZOOMEYE_API_KEY="your_api_key_here" - 运行容器时直接传递（Docker）：
docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest
与 AI 助手交互
- 使用上述安装方法之一启动服务器。
- 配置你的 AI 助手（Claude Desktop、Cursor、Windsurf、Cline、Continue、Zed 等）以使用该服务器。
- 使用自然语言查询网络信息。
配置示例
可在 Claude 设置中添加配置，也可在 Zed 的 settings.json 中添加配置（具体配置格式暂未在提供资料中展开）。
搜索语法指南
- 搜索范围涵盖设备（IPv4、IPv6）和网站（域名）。
- 搜索字符串在“全局”模式下匹配关键词，包括 HTTP、SSH、FTP 等多种协议的内容。
- 搜索字符串不区分大小写并进行分词匹配。使用 == 时强制执行区分大小写的精确匹配及严格语法。
- 搜索字符串请使用引号（如 "Cisco System" 或 'Cisco System'）。如果搜索字符串包含引号，使用转义字符，如 "a"b"。如果搜索字符串包含括号，使用转义字符，如 portinfo()。
- 更详细的搜索语法规则可在 prompts.py 中查看。
- 有关 ZoomEye 搜索 API 的更多信息，请参考 ZoomEye API v2 文档。
缓存与分页
- 响应基于查询参数进行缓存。
- 缓存时长可配置（默认 1 小时）。
- 可在查询中将 ignore_cache 设置为 true 以绕过缓存。
- 可使用 fields 参数请求特定字段。
- 对于返回大量结果的查询，可以分页浏览。
调试与故障排除
- 可使用 Model Context Protocol Inspector 调试 MCP 服务器，通过模拟客户端交互进行测试。
- 认证错误：确保 ZoomEye API 密钥正确并正确设置为环境变量；检查 API 密钥是否过期或被撤销。
- 连接问题：验证互联网连接；检查 ZoomEye API 是否出现停机。
- 无结果：查询可能过于具体或包含语法错误；尝试简化查询或使用不同搜索词。
- 速率限制：ZoomEye API 根据账户类型有速率限制；分散请求或升级账户以提高限制。
适用场景
- 在 AI 助手或开发环境中通过自然语言查询网络资产信息。
- 搜索全球互联网资产并追踪实时变更。
- 安全研究人员和开发人员获取网络空间资产情报。
限制
- 需要使用 ZoomEye API 密钥，并可能受账户类型的速率限制。
- 免费试用为 7 天免费访问 ZoomEye MCP（需关注 Twitter @zoomeye_team 并私信 "MCP" 和 MCP 设置截图以获取）。
- 缓存默认 1 小时，可通过参数绕过。
开源与许可
mcp-server-zoomeye 在 MIT 许可证下发布，允许自由使用、修改和分发，但需遵守 MIT 许可证的条款和条件。欢迎贡献，包括新工具、功能增强和文档改进。
