📌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 enables Large Language Models (LLMs) to obtain network asset information by querying ZoomEye using dorks and other parameters.

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: 1).
    • pagesize (integer): Number of records per page (default: 10, max: 1000).
    • fields (string): The fields to return, separated by commas.
    • sub_type (string): Data type (supports v4, v6, and web; default: v4).
    • facets (string): Statistical items, separated by commas.
    • ignore_cache (boolean): Whether to ignore the cache.

Usage Guide

Basic Usage

1. Start the server using one of the installation methods.
2. Configure your AI assistant to use the server.
3. Query network information using natural language.

Search Syntax Guide

• The search covers devices (IPv4, IPv6) and websites (domains).
• Search strings are case-insensitive and can be segmented for matching.
• Use quotes for search strings. If your search string contains quotes or parentheses, use escape characters.

For more detailed search syntax rules, refer to prompts.py in the source code.

Getting Started

Prerequisites

1. ZoomEye API Key:
   • Register for an account at ZoomEye and obtain your API key.
2. Python Environment:
   • Requires Python 3.10 or higher. Docker can be used as an alternative.

Installation

Using PIP

pip install mcp-server-zoomeye

Run it as a script:

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

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

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

Using uvx to run mcp-server-zoomeye

uv pip install mcp-server-zoomeye

Configuration

Environment Variables

• ZOOMEYE_API_KEY: Your ZoomEye API key for authentication.

Set this variable in several ways, such as exporting in your shell session or directly when running the container.

Example Interactions

Retrieve global Apache Tomcat assets

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

Debugging and Troubleshooting

Common Issues

1. Authentication Errors: Check that your API key is correct and set as an environment variable.
2. Connection Issues: Verify your internet connection and check if the ZoomEye API is down.
3. No Results: Your query might be too specific or contain syntax errors.
4. Rate Limiting: ZoomEye has rate limits based on your account type.

Advanced Usage

Caching

Cached responses improve performance and can be configured to bypass.

Custom Fields and Pagination

Request specific fields using the fields parameter and paginate results with the page parameter.

Contributing

Contributions to mcp-server-zoomeye are welcome. For examples of other MCP servers, see the GitHub repository. Pull requests are encouraged!

License

mcp-server-zoomeye is licensed under the MIT License. You are free to use, modify, and distribute the software under the terms of the MIT License.