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.
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:
- Start the server using one of the installation methods above
- Configure your AI assistant (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, etc.) to use the server
- Query network information using natural language
searchexample
Search Syntax Guide
- Search Scope covers devices (IPv4, IPv6) and websites (domains).
- When entering a search string, the system will match keywords in "global" mode, including content from various protocols such as HTTP, SSH, FTP, etc. (e.g., HTTP/HTTPS protocol headers, body, SSL, title, and other protocol banners).
- Search strings are case-insensitive and will be segmented for matching (the search results page provides a " segmentation" test feature). When using == for search, it enforces exact case-sensitive matching with strict syntax.
- Please use quotes for search strings (e.g., "Cisco System" or 'Cisco System'). If the search string contains quotes, use the escape character, e.g.,"a"b". If the search string contains parentheses, use the escape character, e.g., portinfo().
You can see more detailed search syntax rules in prompts.py.
For more information on the ZoomEye Search API, refer to the ZoomEye API v2 documentation.
Getting Started
Prerequisites
- ZoomEye API Key
- Python Environment
Installation
Using PIP
Alternatively, you can install
mcp-server-zoomeye via pip:After installation, you can run it as a script using the following command:
Using Docker
You can also run the ZoomEye MCP server using Docker:
Pull from Docker Hub
Note: We provide multi-architecture Docker images that supportlinux/amd64andlinux/arm64platforms and can run on Intel/AMD and ARM (such as Apple Silicon) processors.
Build from Source
Alternatively, you can build the Docker image from source:
Using uv
`uv` is a fast Python package installer and resolver written in Rust. It's a modern alternative to pip that offers significant performance improvements.
Installation of uv
Using uvx to run mcp-server-zoomeye
No specific installation is required when using `uvx`, which allows you to run Python packages directly:
Installing with uv
Alternatively, you can install the package using uv:
Configuration
Environment Variables
The ZoomEye MCP server requires the following environment variable:
ZOOMEYE_API_KEY: Your ZoomEye API key for authentication
You can set this environment variable in several ways:
- Export in your shell session:
- Pass directly when running the container (for Docker):
Configure Claude.app
Add the following in Claude settings:
Configure Zed
Add the following in Zed's settings.json:
Example Interactions
Example 1: Retrieve global Apache Tomcat assets
Response:
Debugging and Troubleshooting
Using MCP Inspector
The Model Context Protocol Inspector is a tool that helps debug MCP servers by simulating client interactions. You can use it to test your ZoomEye MCP server:
Common Issues
- Authentication Errors
- Connection Issues
- No Results
- Rate Limiting
Advanced Usage
Caching
The ZoomEye MCP server implements caching to improve performance and reduce API calls:
- Responses are cached based on the query parameters
- Cache duration is configurable (default: 1 hour)
- You can bypass the cache by setting
ignore_cachetotruein your query
Custom Fields
You can request specific fields in your query results by using the
fields parameter:Pagination
For queries that return many results, you can paginate through them:
Contributing
We encourage contributions to mcp-server-zoomeye to help expand and improve its functionality. Whether it's adding new related tools, enhancing existing features, or improving documentation, your input is valuable.
For examples of other MCP servers and implementation patterns, see:
https://github.com/modelcontextprotocol/servers
Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make mcp-server-zoomeye more robust and practical.
License
mcp-server-zoomeye is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more information, see the LICENSE file in the project repository.
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.
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:
- Start the server using one of the installation methods above
- Configure your AI assistant (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, etc.) to use the server
- Query network information using natural language
searchexample
Search Syntax Guide
- Search Scope covers devices (IPv4, IPv6) and websites (domains).
- When entering a search string, the system will match keywords in "global" mode, including content from various protocols such as HTTP, SSH, FTP, etc. (e.g., HTTP/HTTPS protocol headers, body, SSL, title, and other protocol banners).
- Search strings are case-insensitive and will be segmented for matching (the search results page provides a " segmentation" test feature). When using == for search, it enforces exact case-sensitive matching with strict syntax.
- Please use quotes for search strings (e.g., "Cisco System" or 'Cisco System'). If the search string contains quotes, use the escape character, e.g.,"a"b". If the search string contains parentheses, use the escape character, e.g., portinfo().
You can see more detailed search syntax rules in prompts.py.
For more information on the ZoomEye Search API, refer to the ZoomEye API v2 documentation.
Getting Started
Prerequisites
- ZoomEye API Key
- Python Environment
Installation
Using PIP
Alternatively, you can install
mcp-server-zoomeye via pip:After installation, you can run it as a script using the following command:
Using Docker
You can also run the ZoomEye MCP server using Docker:
Pull from Docker Hub
Note: We provide multi-architecture Docker images that supportlinux/amd64andlinux/arm64platforms and can run on Intel/AMD and ARM (such as Apple Silicon) processors.
Build from Source
Alternatively, you can build the Docker image from source:
Using uv
`uv` is a fast Python package installer and resolver written in Rust. It's a modern alternative to pip that offers significant performance improvements.
Installation of uv
Using uvx to run mcp-server-zoomeye
No specific installation is required when using `uvx`, which allows you to run Python packages directly:
Installing with uv
Alternatively, you can install the package using uv:
Configuration
Environment Variables
The ZoomEye MCP server requires the following environment variable:
ZOOMEYE_API_KEY: Your ZoomEye API key for authentication
You can set this environment variable in several ways:
- Export in your shell session:
- Pass directly when running the container (for Docker):
Configure Claude.app
Add the following in Claude settings:
Configure Zed
Add the following in Zed's settings.json:
Example Interactions
Example 1: Retrieve global Apache Tomcat assets
Response:
Debugging and Troubleshooting
Using MCP Inspector
The Model Context Protocol Inspector is a tool that helps debug MCP servers by simulating client interactions. You can use it to test your ZoomEye MCP server:
Common Issues
- Authentication Errors
- Connection Issues
- No Results
- Rate Limiting
Advanced Usage
Caching
The ZoomEye MCP server implements caching to improve performance and reduce API calls:
- Responses are cached based on the query parameters
- Cache duration is configurable (default: 1 hour)
- You can bypass the cache by setting
ignore_cachetotruein your query
Custom Fields
You can request specific fields in your query results by using the
fields parameter:Pagination
For queries that return many results, you can paginate through them:
Contributing
We encourage contributions to mcp-server-zoomeye to help expand and improve its functionality. Whether it's adding new related tools, enhancing existing features, or improving documentation, your input is valuable.
For examples of other MCP servers and implementation patterns, see:
https://github.com/modelcontextprotocol/servers
Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make mcp-server-zoomeye more robust and practical.
License
mcp-server-zoomeye is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more information, see the LICENSE file in the project repository.