ZoomEye MCP 服务器

一个基于查询条件提供网络资产信息的模型上下文协议（MCP）服务器。该服务器允许大型语言模型（LLMs）通过使用 dorks 和其他搜索参数来查询 ZoomEye 获取网络资产信息。

此MCP服务器与AI助手和开发环境如Claude Desktop、Cursor、Windsurf、Cline、Continue及Zed集成，使它们能够通过自然语言交互搜索并分析互联网连接设备、服务和漏洞。

特性

• 使用dorks查询ZoomEye以获取网络资产信息
• 缓存机制以提高性能并减少API调用
• 自动重试机制处理失败的API请求
• 全面的错误处理和日志记录

可用工具

• zoomeye_search - 根据查询条件获取网络资产信息。
  • 必需参数：
    • qbase64 (字符串): 用于ZoomEye搜索的基础64编码查询字符串
  • 可选参数：
    • page (整数): 查看资产页码，默认为1
    • pagesize (整数): 每页记录数，默认为10，最大值为1000
    • fields (字符串): 要返回的字段，多个字段之间用逗号分隔
    • sub_type (字符串): 数据类型，支持v4, v6, 和web。默认为v4
    • facets (字符串): 统计项，如果有多个则用逗号分隔
    • ignore_cache (布尔值): 是否忽略缓存

使用指南

基本使用

一旦服务器运行起来，您就可以通过您的AI助手或开发环境与其进行交互。以下是使用方法：

1. 启动服务器：使用上述任一安装方法启动服务器
2. 配置您的AI助手 (例如 Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed 等) 使其使用该服务器
3. 使用自然语言查询网络信息

搜索语法指南

• 搜索范围涵盖设备(IPv4, IPv6)和网站(域名)。
• 输入搜索字符串时，系统将以“全局”模式匹配关键词，包括来自各种协议的内容，如HTTP、SSH、FTP等（例如，HTTP/HTTPS协议头、正文、SSL、标题及其他协议横幅）。
• 搜索字符串不区分大小写，并将被分段匹配（搜索结果页面提供了“分词”测试功能）。当使用==进行搜索时，它会强制执行严格语法下的精确大小写匹配。
• 请对搜索字符串使用引号（例如 "Cisco System" 或 'Cisco System'）。如果搜索字符串包含引号，请使用转义字符，例如"a"b"。如果搜索字符串包含括号，请使用转义字符，例如portinfo()。

更多详细的搜索语法规则见 prompts.py。

有关ZoomEye搜索API的更多信息，请参阅ZoomEye API v2文档。

开始使用

前提条件

1. ZoomEye API密钥

   • 在ZoomEye注册账户
   • 从账户设置中获取您的API密钥
   • 该API密钥将用于验证您对ZoomEye API的请求

2. Python环境

   • 需要Python 3.10或更高版本
   • 或者，您可以使用Docker运行服务器而无需安装Python

安装

使用PIP

或者，您可以通过pip安装mcp-server-zoomeye:

bash
pip install mcp-server-zoomeye

安装后，可以使用以下命令作为脚本运行：

bash
python -m mcp_server_zoomeye

使用Docker

您也可以使用Docker运行ZoomEye MCP服务器：

从Docker Hub拉取

bash

拉取最新镜像

docker pull zoomeyeteam/mcp-server-zoomeye:latest

使用您的API密钥运行容器

docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest> 注意: 我们提供支持 linux/amd64 和 linux/arm64 平台的多架构 Docker 镜像，可以在 Intel/AMD 和 ARM（如 Apple Silicon）处理器上运行。

从源代码构建

或者，您可以从源代码构建 Docker 镜像：

bash

克隆仓库

git clone https://github.com/zoomeye-ai/mcp_zoomeye.git
cd mcp_zoomeye

构建 Docker 镜像

docker build -t zoomeyeteam/mcp-server-zoomeye:local .

运行容器

docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:local

使用 uv

uv 是一个用 Rust 编写的快速 Python 包安装器和解析器。它是 pip 的现代替代品，提供了显著的性能改进。

安装 uv

bash

使用 curl 安装 uv (macOS/Linux)

curl -LsSf https://astral.sh/uv/install.sh | sh

或者使用 PowerShell (Windows)

irm https://astral.sh/uv/install.ps1 | iex

或者使用 Homebrew (macOS)

brew install uv

使用 uvx 运行 mcp-server-zoomeye

使用 uvx 时不需要特定的安装步骤，它允许您直接运行 Python 包：

使用 uv 安装

或者，您可以使用 uv 安装包：

bash

在当前环境中安装

uv pip install mcp-server-zoomeye

或者在新的虚拟环境中创建并安装

uv venv
uv pip install mcp-server-zoomeye

配置

环境变量

ZoomEye MCP 服务器需要以下环境变量：

• ZOOMEYE_API_KEY: 您的 ZoomEye API 密钥用于身份验证

您可以以多种方式设置此环境变量：

1. 在 shell 会话中导出：
   bash
   export ZOOMEYE_API_KEY="your_api_key_here"

2. 在运行容器时直接传递 (对于 Docker)：
   bash
   docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest

配置 Claude.app

在 Claude 设置中添加以下内容：

json
"mcpServers": {
"zoomeye": {
"command": "uvx",
"args": ["mcp-server-zoomeye"],
"env": {
"ZOOMEYE_API_KEY": "your_api_key_here"
}
}
}

json
"mcpServers": {
"zoomeye": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "ZOOMEYE_API_KEY=your_api_key_here", "zoomeyeteam/mcp-server-zoomeye:latest"],
"env": {
"ZOOMEYE_API_KEY": "your_api_key_here"
}
}
}

json
"mcpServers": {
"zoomeye": {
"command": "python",
"args": ["-m", "mcp_server_zoomeye"],
"env": {
"ZOOMEYE_API_KEY": "your_api_key_here"
}
}
}

配置 Zed

在 Zed 的 settings.json 中添加以下内容：

json
"context_servers": [
"mcp-server-zoomeye": {
"command": "uvx",
"args": ["mcp-server-zoomeye"],
"env": {
"ZOOMEYE_API_KEY": "your_api_key_here"
}
}
],

json
"context_servers": {
"mcp-server-zoomeye": {
"command": "python",
"args": ["-m", "mcp_server_zoomeye"],
"env": {
"ZOOMEYE_API_KEY": "your_api_key_here"
}
}
},

示例交互

示例 1：检索全球 Apache Tomcat 资产

json
{
"name": "zoomeye_search",
"arguments": {
"qbase64": "app="Apache Tomcat""
}
}

响应：
json
{
"code": 60000,
"message": "success",
"total": 163139107,
"query": "title="cisco vpn"",
"data": [
{
"url": "https://1.1.1.1:443",
"ssl.jarm": "29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa",
"ssl.ja3s": "45094d08156d110d8ee97b204143db14",
"iconhash_md5": "f3418a443e7d841097c714d69ec4bcb8",
"robots_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
"security_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
"ip": "1.1.1.1",
"domain": "www.google.com",
"hostname": "SPACEX",
"os": "windows",
"port": 443,
"service": "https",
"title": ["GoogleGoogle appsGoogle Search"],
"version": "1.1.0",
"device": "webcam",
"rdns": "c01031-001.cust.wallcloud.ch",
"product": "OpenSSD",
"header": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
"header_hash": "27f9973fe57298c3b63919259877a84d",
"body": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
"body_hash": "84a18166fde3ee7e7c974b8d1e7e21b4",
"banner": "SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3",
"update_time": "2024-07-03T14:34:10",
"header.server.name": "nginx",
"header.server.version": "1.8.1",
"continent.name": "Europe",
"country.name": "Germany",
"province.name": "Hesse",
"city.name": "Frankfurt",
"lon": "118.753262",
"lat": "32.064838",
"isp.name": "aviel.ru",
"organization.name": "SERVISFIRST BANK",
"zipcode": "210003",
"idc": 0,
"honeypot": 0,
"asn": 4837,
"protocol": "tcp",
"ssl": "SSL Certificate Version: TLS 1.2 CipherSuit: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256...",
"primary_industry": "Finance",
"sub_industry": "bank",
"rank": 60
}
]
}## 调试和故障排除

使用MCP Inspector

Model Context Protocol Inspector 是一个通过模拟客户端交互来帮助调试MCP服务器的工具。您可以使用它来测试您的ZoomEye MCP服务器：

bash

对于uvx安装

npx @modelcontextprotocol/inspector uvx mcp-server-zoomeye

如果是本地开发

cd path/to/servers/src/mcp_server_zoomeye
npx @modelcontextprotocol/inspector uv run mcp-server-zoomeye

常见问题

1. 认证错误

   • 确保您的ZoomEye API密钥正确且已正确设置为环境变量
   • 检查您的API密钥是否未过期或被撤销

2. 连接问题

   • 验证您的互联网连接
   • 检查ZoomEye API是否正在经历停机时间

3. 无结果

   • 您的查询可能过于具体或包含语法错误
   • 尝试简化您的查询或使用不同的搜索词

4. 速率限制

   • ZoomEye API根据您的账户类型有速率限制
   • 请间隔发送请求或升级您的账户以获得更高的限制

高级用法

缓存

ZoomEye MCP服务器实现了缓存以提高性能并减少API调用次数：

• 响应基于查询参数进行缓存
• 缓存持续时间可配置（默认：1小时）
• 您可以通过在查询中将ignore_cache设置为true来绕过缓存

自定义字段

您可以通过使用fields参数在查询结果中请求特定字段：

json
{
"name": "zoomeye_search",
"arguments": {
"qbase64": "app="Apache"",
"fields": "ip,port,domain,service,os,country,city"
}
}

分页

对于返回大量结果的查询，您可以对其进行分页：

json
{
"name": "zoomeye_search",
"arguments": {
"qbase64": "app="Apache"",
"page": 2,
"pagesize": 20
}
}

贡献

我们鼓励对mcp-server-zoomeye进行贡献，以帮助扩展和完善其功能。无论是添加新的相关工具、增强现有功能还是改进文档，您的输入都是宝贵的。

有关其他MCP服务器和实现模式的例子，请参阅：
https://github.com/modelcontextprotocol/servers

欢迎提交Pull Request！随时贡献新想法、修复bug或增强功能，使mcp-server-zoomeye更加健壮和实用。

许可证

mcp-server-zoomeye 根据MIT许可证发布。这意味着您可以自由地使用、修改和分发该软件，但需遵守MIT许可证的条款和条件。更多信息，请参阅项目仓库中的LICENSE文件。