mcp_zoomeye

The ZoomEye MCP Server provides real-time network asset information by querying the ZoomEye API through dorks and search parameters. It exposes a single MCP endpoint (zoomeye) that your MCP-compatible AI assistants or development environments can query to retrieve asset data, using the available tool zoomeye_search. This tool accepts a base64-encoded query string (qbase64) and optional pagination and field-selection parameters, returning results that your AI assistant can surface in conversations or inject into workflows. The server includes caching, automatic retry, and robust error handling to improve reliability during calls to ZoomEye.

To use it, start the server with your preferred method (Python, uv, or Docker) and configure your MCP client (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, etc.) to point to the zoomeye MCP server. Once configured, you can perform ZoomEye searches through natural language prompts that translate to the zoomeye_search tool parameters. For example, you can request network assets matching a specific dork, specify the fields you want, control page size, and choose data types (v4, v6, or web) as needed. The integration is designed to let LLMs fetch up-to-date asset data securely via the ZoomEye API key you provide via environment variables.

Prerequisites:

• A ZoomEye API key (ZOOMEYE_API_KEY).
• Python 3.10+ installed, or Docker if you prefer containerized usage.
• Optional: uv for fast Python execution or uvx if you want to run the package without a traditional Python install.

Install options:

1. Using pip (recommended if you have Python installed locally)

pip install mcp-server-zoomeye

Run:

python -m mcp_server_zoomeye

2. Using Docker

# 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

3. Using uv (optional, for faster Python installs)

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the package with uvx (assuming you have uvx installed)
uvx mcp-server-zoomeye

4. Build from source (optional)

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

# Install dependencies and run
pip install -e .
python -m mcp_server_zoomeye

Environment variable usage:

• ZOOMEYE_API_KEY: Your ZoomEye API key. Set it in your shell or pass to Docker with -e ZOOMEYE_API_KEY=your_api_key_here.

Tips and common issues:

• Ensure your ZOOMEYE_API_KEY is valid and has the necessary access for the API endpoints used by the server.
• If you see authentication errors, double-check that the environment variable is correctly passed to the process or container.
• When running behind proxies, configure network access to ZoomEye endpoints as required by your environment.
• If using Docker, remember that the container's internal path and network isolation may affect how you supply environment variables; prefer -e for environment variables.
• The available tool zoomeye_search supports qbase64 (required), with optional page, pagesize, fields, sub_type, facets, and ignore_cache parameters. Base64-encode your query string before sending.
• For Claude.app integration, you can embed the provided JSON snippet under mcpServers with the appropriate command and env, as shown in the setup examples.
• If you encounter performance issues, leverage the server-side caching and check the logs for retry behavior when API calls fail.