playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

ZoomEye MCP server

Integrates with ZoomEye API to enable network asset reconnaissance through specialized search tools, supporting dork queries, IP filtering, and field selection with built-in caching and error handling for cybersecurity workflows.
Back to servers
Setup instructions
Provider
ZoomEye
Release date
Mar 15, 2025
Language
Python
Stats
44 stars
View on GitHub

ZoomEye MCP Server provides network asset information to Large Language Models (LLMs) through the Model Context Protocol. This server enables AI assistants to query ZoomEye's extensive database of cyber assets using search parameters and dorks, delivering real-time intelligence about internet-connected devices and services.

Installation Options

Using PIP

pip install mcp-server-zoomeye

After installation, run the server with:

python -m mcp_server_zoomeye

Using Docker

You can run the server using Docker without installing Python:

# 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

The Docker images support both linux/amd64 and linux/arm64 platforms.

Using uv

You can use the uv package manager for faster installation:

# Install uv first (if you don't have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install in the current environment
uv pip install mcp-server-zoomeye

# Or run directly without installation using uvx
uvx mcp-server-zoomeye

Getting Your API Key

To use this MCP server, you'll need a ZoomEye API key:

  1. Go to https://www.zoomeye.ai
  2. Register or log in
  3. Click your avatar → Profile
  4. Copy your API-KEY
  5. Set the environment variable: export ZOOMEYE_API_KEY="your_api_key_here"

Configuring AI Assistants

Claude Desktop Configuration

Add this to 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"
    }
  }
}

Using pip installation:

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

Zed Configuration

Add to 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"
    }
  }
],

Using the ZoomEye MCP Server

Available Tool

The server provides one main tool:

  • zoomeye_search - Get network asset information based on query conditions
    • Required parameter:
      • 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, max 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
      • ignore_cache (boolean): Whether to ignore the cache

Basic Query Example

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

Advanced Usage Examples

Retrieving specific fields:

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

Pagination:

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

Bypass caching:

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

Search Syntax Guide

  • Search covers devices (IPv4, IPv6) and websites (domains)
  • Searches are case-insensitive by default
  • Use quotes for search strings (e.g., "Cisco System" or 'Cisco System')
  • Use escape characters for quotes in search strings (e.g., "a"b")
  • Use escape characters for parentheses in search strings (e.g., portinfo())
  • Use == for exact case-sensitive matching

Troubleshooting

Using MCP Inspector

To debug the server, use the MCP Inspector:

# 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

  1. Authentication Errors

    • Verify your ZoomEye API key is correct and properly set
    • Check if your API key has expired

  2. Connection Issues

    • Verify your internet connection
    • Check if the ZoomEye API is available

  3. No Results

    • Your query might be too specific
    • Try simplifying your search terms

  4. Rate Limiting

    • Space out your requests
    • Consider upgrading your ZoomEye account for higher limits

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "zoomeye" '{"command":"python","args":["-m","mcp_server_zoomeye"],"env":{"ZOOMEYE_API_KEY":"your_api_key_here"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later