ZoomEye MCP Server

🚀 ZoomEye MCP 服务

一个基于查询条件提供网络资产信息的模型上下文协议（MCP）服务。此服务支持大语言模型（LLM）通过使用 dork 和其他搜索参数查询 ZoomEye，获取网络资产信息。

🔔 公告

🎉 我们很高兴地宣布，ZoomEye MCP 服务现已正式开源发布——这是一个强大的模型上下文协议（MCP）服务，可为 AI 助手和开发环境提供实时网络资产情报。

🚀 免费试用：免费体验 ZoomEye MCP 7 天！ 免费体验 ZoomEye MCP——由 AI 驱动的网络空间资产搜索引擎，畅享完整的 7 天免费使用！

🔍 搜索全球互联网资产、追踪实时变化，并在一处获取 AI 驱动的洞察。

👉 领取方式：

1. 在 Twitter 上关注我们：@zoomeye_team
2. 私信发送“MCP”和你的 MCP 配置截图
3. 即刻获取 7 天会员资格

🎁 限时免费试用——立即体验 AI 资产搜索的强大功能！

💡 提供有价值并被官方采纳的反馈，即可解锁更多奖励！

🔧 完全兼容主流 MCP 环境：

• Claude Desktop
• Cursor
• Windsurf
• Cline
• Continue
• Zed
• Cherry Studio
• Chatbox

🔗 在以下平台探索 ZoomEye MCP 服务：

• GitHub：zoomeye-ai/mcp_zoomeye
• MCP.so：mcp.so/server/mcp_zoomeye
• Cursor Directory：cursor.directory/mcp/zoomeye
• Pulse MCP：pulsemcp.com/servers/zoomeye
• Glama MCP：glama.ai/mcp/servers

欢迎大家使用、探索并参与贡献！

🔑 如何获取 ZoomEye API 密钥？

使用此 MCP 服务需要 ZoomEye API 密钥。

1. 前往 https://www.zoomeye.ai

2. 注册或登录

3. 点击头像 → 个人资料

4. 复制你的 API-KEY

5. 设置环境变量：

   export ZOOMEYE_API_KEY="your_api_key_here"

功能

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

可用工具

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

使用指南

基本用法

服务启动后，你可以通过 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 Search API 的更多信息，请参阅 ZoomEye API v2 文档。

开始使用

前置条件

1. ZoomEye API 密钥

   • 在 ZoomEye 注册账号
   • 在账号设置中获取 API 密钥
   • API 密钥用于验证你向 ZoomEye API 发出的请求

2. Python 环境

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

安装

使用 PIP

你也可以通过 pip 安装 mcp-server-zoomeye：

pip install mcp-server-zoomeye

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

python -m mcp_server_zoomeye

使用 Docker

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

从 Docker Hub 拉取

# Pull the latest image
docker pull zoomeyeteam/mcp-server-zoomeye:latest

# Run the container with your API key
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 镜像：

# Clone the repository
git clone https://github.com/zoomeye-ai/mcp_zoomeye.git
cd mcp_zoomeye

# Build the Docker image
docker build -t zoomeyeteam/mcp-server-zoomeye:local .

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

使用 uv

uv 是一款使用 Rust 编写的快速 Python 包安装器和解析器。它是 pip 的现代替代方案，性能显著提升。

安装 uv

# Install uv using curl (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using PowerShell (Windows)
irm https://astral.sh/uv/install.ps1 | iex

# Or using Homebrew (macOS)
brew install uv

使用 uvx 运行 mcp-server-zoomeye

使用 uvx 无需进行专门安装，即可直接运行 Python 包：

使用 uv 安装

你也可以使用 uv 安装此包：

# Install in the current environment
uv pip install mcp-server-zoomeye

# Or create and install in a new virtual environment
uv venv
uv pip install mcp-server-zoomeye

配置

环境变量

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

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

你可以通过以下几种方式设置此环境变量：

1. 在 shell 会话中导出：

   export ZOOMEYE_API_KEY="your_api_key_here"
   

2. 运行容器时直接传入（适用于 Docker）：

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

配置 Claude.app

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

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

"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"
    }
  }
}

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

配置 Zed

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

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

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

交互示例

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

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

响应：

{
  "code": 60000,
  "message": "success",
  "total": 163139107,
  "query": "app=\"Apache Tomcat\"",
  "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 服务：

# For uvx installation
npx @modelcontextprotocol/inspector uvx mcp-server-zoomeye

# If developing locally
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 参数，可在查询结果中请求特定字段：

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

分页

对于返回大量结果的查询，可以分页浏览：

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

贡献

我们欢迎为 mcp-server-zoomeye 贡献代码，以扩展和改进其功能。无论是添加相关工具、增强现有功能，还是改进文档，你的贡献都很有价值。

如需查看其他 MCP 服务的示例和实现模式，请参阅： https://github.com/modelcontextprotocol/servers

欢迎提交拉取请求！欢迎贡献新想法、错误修复或改进，让 mcp-server-zoomeye 更加完善实用。

许可证

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