MCP HubMCP Hub
zoomeye-ai

mcp_zoomeye

by: zoomeye-ai

A Model Context Protocol server that provides network asset information based on query conditions. This server allows LLMs to obtain network asset information and supports querying network asset information by zoomeye dork etc.

23created 15/03/2025
Visit
network
API

📌Overview

Purpose: To provide network asset information based on user queries, enabling Large Language Models (LLMs) to gain insights from ZoomEye through natural language interactions.

Overview: The ZoomEye MCP Server is designed to facilitate the retrieval of data about internet-connected devices, services, and vulnerabilities by leveraging ZoomEye's search capabilities. It integrates seamlessly with various AI assistants and development environments, allowing users to query network asset information efficiently and effectively.

Key Features:

  • Query Capability: Users can query ZoomEye for network asset information using dorks and various search parameters, enhancing the ability to gather targeted data.

  • Caching Mechanism: The server includes a caching system that improves performance by reducing the number of API calls needed for repeated queries. This leads to faster response times and reduced load on the API.

  • Robust Error Handling: It has an automatic retry mechanism for handling failed API requests, along with comprehensive error logging that aids in diagnosing issues quickly and efficiently.

ZoomEye MCP Server

A Model Context Protocol (MCP) server that provides network asset information based on query conditions. This server allows Large Language Models (LLMs) to obtain network asset information by querying ZoomEye using dorks and other search parameters.

This MCP server integrates with AI assistants and development environments like Claude Desktop, Cursor, Windsurf, Cline, Continue, and Zed, enabling them to search for and analyze internet-connected devices, services, and vulnerabilities through natural language interactions.

Features

  • Query ZoomEye for network asset information using dorks
  • Caching mechanism to improve performance and reduce API calls
  • Automatic retry mechanism for failed API requests
  • Comprehensive error handling and logging

Available Tools

  • zoomeye_search - Get network asset information based on query conditions.
    • Required parameters:
      • qbase64 (string): Base64 encoded query string for ZoomEye search
    • Optional parameters:
      • page (integer): View asset page number, default is 1
      • pagesize (integer): Number of records per page, default is 10, maximum is 1000
      • fields (string): The fields to return, separated by commas
      • sub_type (string): Data type, supports v4, v6, and web. Default is v4
      • facets (string): Statistical items, separated by commas if there are multiple
      • ignore_cache (boolean): Whether to ignore the cache

Usage Guide

Basic Usage

Once the server is running, you can interact with it through your AI assistant or development environment. Here's how to use it:

  1. Start the server using one of the installation methods
  2. Configure your AI assistant (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, etc.) to use the server
  3. Query network information using natural language

Search Syntax Guide

  • Search scope covers devices (IPv4, IPv6) and websites (domains).
  • The system matches keywords in "global" mode, including content from various protocols such as HTTP, SSH, FTP (e.g., HTTP/HTTPS protocol headers, body, SSL, title, and other protocol banners).
  • Search strings are case-insensitive and segmented for matching. Using == enforces exact case-sensitive matching with strict syntax.
  • Use quotes for search strings (e.g., "Cisco System" or 'Cisco System'). Use escape characters for quotes and parentheses within search strings (e.g., a\"b, portinfo\(\)).

For more information on the ZoomEye Search API, refer to the ZoomEye API v2 documentation.

Getting Started

Prerequisites

  1. ZoomEye API Key

    • Register for an account at ZoomEye
    • Obtain your API key from your account settings
    • The API key is used to authenticate your requests to the ZoomEye API

  2. Python Environment

    • Python 3.10 or higher is required
    • Alternatively, use Docker to run the server without installing Python

Installation

Using PIP

Install mcp-server-zoomeye via pip:

pip install mcp-server-zoomeye

Run the server:

python -m mcp_server_zoomeye

Using Docker

Pull from Docker Hub

docker pull zoomeyeteam/mcp-server-zoomeye:latest

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

Note: Multi-architecture Docker images support linux/amd64 and linux/arm64 platforms.

Build from Source

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

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

Using uv

uv is a fast Python package installer and resolver written in Rust.

Installation of uv

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

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

# macOS Homebrew
brew install uv

Using uvx to run mcp-server-zoomeye

Run Python packages directly with uvx.

Installing with uv

uv pip install mcp-server-zoomeye

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

Configuration

Environment Variables

Set your ZoomEye API key for authentication:

export ZOOMEYE_API_KEY="your_api_key_here"

Or pass it directly when running Docker:

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

Configure Claude.app

Add the following in Claude settings:

Using uvx

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

Using docker

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

Installed via pip

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

Configure Zed

Add the following in Zed's settings.json:

Using uvx

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

Installed via pip

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

Example Interactions

Example 1: Retrieve global Apache Tomcat assets

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

Response:

{
  "code": 60000,
  "message": "success",
  "total": 163139107,
  "query": "title=\"cisco vpn\"",
  "data": [
    {
      "url": "https://1.1.1.1:443",
      "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",
      "product": "OpenSSD",
      "header": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
      "banner": "SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3",
      "update_time": "2024-07-03T14:34:10",
      "header.server.name": "nginx",
      "continent.name": "Europe",
      "country.name": "Germany",
      "province.name": "Hesse",
      "city.name": "Frankfurt",
      "isp.name": "aviel.ru",
      "organization.name": "SERVISFIRST BANK",
      "zipcode": "210003",
      "asn": 4837,
      "protocol": "tcp",
      "primary_industry": "Finance",
      "sub_industry": "bank",
      "rank": 60
    }
  ]
}

Debugging and Troubleshooting

Using MCP Inspector

The Model Context Protocol Inspector helps debug MCP servers by simulating client interactions. Use it to test your ZoomEye MCP server:

# 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

Common Issues

  • Authentication Errors

    • Ensure your ZoomEye API key is correct and properly set
    • Check that your API key has not expired or been revoked

  • Connection Issues

    • Verify your internet connection
    • Check if the ZoomEye API is experiencing downtime

  • No Results

    • Try simplifying your query or using different search terms

  • Rate Limiting

    • ZoomEye API has rate limits based on account type
    • Space out requests or upgrade your account for higher limits

Advanced Usage

Caching

  • Responses are cached based on query parameters
  • Cache duration is configurable (default: 1 hour)
  • Bypass cache by setting ignore_cache to true in your query

Custom Fields

Request specific fields in query results using the fields parameter:

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

Pagination

Paginate through results:

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

Contributing

Contributions are welcome to expand and improve mcp-server-zoomeye. Pull requests can include new tools, enhancements, or documentation improvements.

For example MCP servers and implementation patterns, see:
https://github.com/modelcontextprotocol/servers

License

mcp-server-zoomeye is licensed under the MIT License. You are free to use, modify, and distribute the software under its terms. See the LICENSE file in the project repository.