Skip to main content
Glama
enesjakozh
zoomeye-ai

ZoomEye MCP Server

Official
by zoomeye-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

ZoomEye MCP 服务器

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

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

特征

  • 使用 dorks 向 ZoomEye 查询网络资产信息

  • 缓存机制以提高性能并减少 API 调用

  • 失败的 API 请求的自动重试机制

  • 全面的错误处理和日志记录

Related MCP server: Shodan-MCP-Server

可用工具

  • zoomeye_search - 根据查询条件获取网络资产信息。

    • 必需参数：

      • qbase64 （字符串）：用于 ZoomEye 搜索的 Base64 编码查询字符串

    • 可选参数：

      • page （整数）：查看资产页码，默认为 1

      • pagesize （整数）：每页记录数，默认为10，最大为1000

      • fields （字符串）：要返回的字段，以逗号分隔

      • sub_type （字符串）：数据类型，支持 v4、v6 和 web。默认为 v4

      • facets （字符串）：统计项，如果有多个，则用逗号分隔

      • 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 的现代替代品，性能显著提升。

紫外线安装

# 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": "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 检查器

模型上下文协议检查器是一款通过模拟客户端交互来帮助调试 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

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

执照

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

Available Tools

3 tools
zoomeye_vuldb_by_idC

Search for detailed vulnerability information by vulnerability ID and return formatted results.

Use this tool to retrieve comprehensive security vulnerability details from the vulnerability
database using a vulnerability identifier (CVE, CNVD, CNNVD). Results include:
ParametersJSON Schema
NameRequiredDescriptionDefault
cve_idYesA valid vulnerability identifier, eg: CVE-XXXX-XXXX,CNVD-XXXX-XXXX,CNNVD-XXXX-XXXX

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavioral traits. It indicates a read-only operation (search/retrieve), but fails to describe output format, pagination, rate limits, or any side effects. The abrupt end ('Results include:') leaves the agent guessing what the tool returns, which is a significant gap for transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, but it is incomplete, ending with 'Results include:' without any continuation. This disrupts the structure and leaves the description unfinished. Every sentence should be complete and purposeful, and this one fails to deliver its intended content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should explain the return values comprehensively. It starts listing results but cuts off, providing zero information about what the formatted results contain. This is a major omission for a tool that only has one parameter and no other documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, with the parameter 'cve_id' described and examples given. The description repeats this information without adding substantial new meaning. Baseline is 3, and since no extra semantics are provided, the score remains at 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search for detailed vulnerability information by vulnerability ID', specifying the verb and resource. It lists the accepted ID formats (CVE, CNVD, CNNVD), which helps the agent understand the tool's scope. However, it does not differentiate from sibling tools like 'zoomeye_search' or 'zoomeye_vuldb_by_keyword', and the incomplete sentence 'Results include:' slightly reduces clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'Use this tool to retrieve...' but provides no guidance on when to use it versus alternatives, such as the sibling tool 'zoomeye_vuldb_by_keyword'. There is no mention of prerequisites, limitations, or exclusions, leaving the agent to infer usage context without explicit advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

zoomeye_vuldb_by_keywordA

Search ZoomEye's vulnerability database for security vulnerabilities based on a specified keyword.

This function queries the ZoomEye vulnerability database to retrieve information about known security vulnerabilities associated with specific products, vendors. Results include vulnerability details such as CVE IDs, severity ratings, affected versions, and vulnerability descriptions.

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYesSearch term to query the vulnerability database. This can be a product name, vendor name (e.g., "nginx", "mysql", "tomcat", "WordPress", "hikvision", "huawei").
page_sizeNoNumber of records per page, default is 10, maximum is 100.

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, but the description only lists output fields without behavioral disclosures like read-only guarantee, rate limits, or authentication needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, though the second paragraph could be shortened without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description reasonably explains return fields (CVE, severity, etc.) and implies pagination via page_size, though total count is omitted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description enhances understanding by providing examples for keyword and clarifying page_size defaults/maximum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches ZoomEye's vulnerability database by keyword, and implicitly distinguishes it from siblings (search vs. by ID).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains it retrieves vulnerability info for products/vendors but does not explicitly compare with zoomeye_search or zoomeye_vuldb_by_id.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedzoomeye_search
    • First observedzoomeye_vuldb_by_id
    • First observedzoomeye_vuldb_by_keyword
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool serves a distinct purpose: one for general asset search, one for vulnerability detail by ID, and one for vulnerability keyword search. There is no overlap in functionality.

Naming Consistency5/5

All tools follow a consistent 'zoomeye_' prefix with snake_case naming: search, vuldb_by_id, vuldb_by_keyword. Pattern is uniform and predictable.

Tool Count4/5

With 3 tools, the set is minimal but appropriate for the ZoomEye domain, covering asset search and vulnerability queries. Slightly thin but reasonable given the focused scope.

Completeness3/5

The tools cover basic search and vulnerability lookup, but lack features like retrieving detailed host info, filtering by specific fields, or obtaining result counts. Some operations are missing for full workflow coverage.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-shodan

    w0h1v
    A
    license
    A
    quality
    A
    maintenance
    MCP server for querying the Shodan API and Shodan CVEDB. This server provides tools for IP lookups, device searches, DNS lookups, vulnerability queries, CPE lookups, and more.
    7
    362 npm
    174
    MIT

  • Shodan-MCP-Server

    X3r0K
    F
    license
    Not graded
    quality
    D
    maintenance
    This is a Model Context Protocol (MCP) server that provides access to the Shodan API. It allows you to programmatically query Shodan for information about devices, vulnerabilities, and more.
    2
    -

  • SurveyHub-MCP

    helGayhub233
    A
    license
    B
    quality
    B
    maintenance
    Aggregates multiple cyberspace search engines (FOFA, Quake, Hunter, ZoomEye) into a unified MCP server, enabling asset search, pagination, statistics, and account info retrieval.
    26
    MIT

Appeared in Searches