ZoomEye MCP Server

ZoomEye MCP Server

用于查询 ZoomEye API 的 MCP 服务器

Category
访问服务器

README

ZoomEye MCP 服务器

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

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

特性

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

可用工具

  • zoomeye_search - 根据查询条件获取网络资产信息。
    • 必需参数：
      • qbase64 (字符串): ZoomEye 搜索的 Base64 编码查询字符串
    • 可选参数：
      • 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. 使用自然语言查询网络信息

searchexample

搜索语法指南

  • 搜索范围涵盖设备（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：

pip install mcp-server-zoomeye

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

python -m mcp_server_zoomeye

使用 Docker

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

从 Docker Hub 拉取

# 拉取最新镜像
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 镜像：

# 克隆存储库
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

# 使用 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 安装软件包：

# 安装在当前环境中
uv pip install mcp-server-zoomeye

# 或者创建并安装在一个新的虚拟环境中
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 设置中添加以下内容：

<details> <summary>使用 uvx</summary>

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

</details>

<details> <summary>使用 docker</summary>

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

</details>

<details> <summary>通过 pip 安装</summary>

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

</details>

配置 Zed

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

<details> <summary>使用 uvx</summary>

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

</details>

<details> <summary>通过 pip 安装</summary>

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

</details>

示例交互

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

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

响应：

{
  "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 服务器：

# 对于 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 参数在查询结果中请求特定字段：

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

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

许可证

mcp-server-zoomeye 在 MIT 许可证下获得许可。 这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。 有关更多信息，请参见项目存储库中的 LICENSE 文件。

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选