ZoomEye MCP Server

1# 🚀 ZoomEye MCP Server
2 
3A 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.
4 
5## 🔔 Announcement
6 
7🎉 We are excited to announce the official open-source release of **ZoomEye MCP Server** — a powerful Model Context Protocol (MCP) server that brings real-time cyber asset intelligence to AI assistants and development environments.
8 
9🚀 Free Trial: 7-Day FREE Access to ZoomEye MCP!
10Experience ZoomEye MCP — the AI-powered cyberspace asset search engine — absolutely free for 7 days!
11 
12🔍 Search global internet assets, track real-time changes, and unlock AI-driven insights — all in one place.
13 
14👉 How to claim:
15 
161. Follow us on Twitter: [@zoomeye_team](https://x.com/zoomeye_team)
172. DM us "MCP" and your MCP setup screenshot
183. Get instant access to your 7-day membership
19 
20🎁 Limited-time free trial — explore the power of AI asset search today!
21 
22💡 Provide insightful feedback that gets officially adopted, and you'll unlock **even more rewards**!
23 
24🔧 Fully compatible with leading MCP environments:
25 
26- Claude Desktop
27- Cursor
28- Windsurf
29- Cline
30- Continue
31- Zed
32- Cherry Studio
33- Chatbox
34 
35🔗 Explore ZoomEye MCP Server on:
36 
37- GitHub: [zoomeye-ai/mcp_zoomeye](https://github.com/zoomeye-ai/mcp_zoomeye)
38- MCP.so: [mcp.so/server/mcp_zoomeye](https://mcp.so/server/mcp_zoomeye/zoomeye-ai)
39- Cursor Directory: [cursor.directory/mcp/zoomeye](https://cursor.directory/mcp/zoomeye)
40- Pulse MCP: [pulsemcp.com/servers/zoomeye](https://www.pulsemcp.com/servers/zoomeye)
41- Glama MCP: [glama.ai/mcp/servers](https://glama.ai/mcp/servers)
42 
43We welcome everyone to use, explore, and contribute!
44 
45## 🔑 How can I get a ZoomEye API key?
46 
47To use this MCP server, you’ll need a ZoomEye API key.
48 
491. Go to https://www.zoomeye.ai
502. Register or log in
513. Click your avatar → **Profile**
524. Copy your **API-KEY**
535. Set the environment variable:
54   
55   `export ZOOMEYE_API_KEY="your_api_key_here"`
56 
57![zoomeye1](./zoomeye1.jpg)
58 
59![zoomeye2](./zoomeye2.jpg)
60 
61## Features
62 
63- Query ZoomEye for network asset information using dorks
64- Caching mechanism to improve performance and reduce API calls
65- Automatic retry mechanism for failed API requests
66- Comprehensive error handling and logging
67 
68## Available Tools
69 
70- `zoomeye_search` - Get network asset information based on query conditions.
71  - Required parameters:
72    - `qbase64` (string): Base64 encoded query string for ZoomEye search
73  - Optional parameters:
74    - `page` (integer): View asset page number, default is 1
75    - `pagesize` (integer): Number of records per page, default is 10, maximum is 1000
76    - `fields` (string): The fields to return, separated by commas
77    - `sub_type` (string): Data type, supports v4, v6, and web. Default is v4
78    - `facets` (string): Statistical items, separated by commas if there are multiple
79    - `ignore_cache` (boolean): Whether to ignore the cache
80 
81## Usage Guide
82 
83### Basic Usage
84 
85Once the server is running, you can interact with it through your AI assistant or development environment. Here's how to use it:
86 
871. **Start the server** using one of the installation methods above
882. **Configure your AI assistant** (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, etc.) to use the server
893. **Query network information** using natural language
90 
91![searchexample](example.png)
92 
93### Search Syntax Guide
94 
95- Search Scope covers devices (IPv4, IPv6) and websites (domains).
96- When entering a search string, the system will match keywords in "global" mode, including content from various
97  protocols such as HTTP, SSH, FTP, etc. (e.g., HTTP/HTTPS protocol headers, body, SSL, title, and other protocol
98  banners).
99- Search strings are case-insensitive and will be segmented for matching (the search results page provides a "
100  segmentation" test feature). When using == for search, it enforces exact case-sensitive matching with strict syntax.
101- Please use quotes for search strings (e.g., "Cisco System" or 'Cisco System'). If the search string contains quotes,
102  use the escape character, e.g.,"a\"b". If the search string contains parentheses, use the escape character, e.g.,
103  portinfo\(\).
104 
105You can see more detailed search syntax rules in [prompts.py](./src/mcp_server_zoomeye/prompts.py).
106 
107For more information on the ZoomEye Search API, refer to the [ZoomEye API v2 documentation](https://www.zoomeye.ai/doc).
108 
109## Getting Started
110 
111### Prerequisites
112 
1131. **ZoomEye API Key**
114   
115   - Register for an account at [ZoomEye](https://www.zoomeye.ai/)
116   - Obtain your API key from your account settings
117   - The API key will be used to authenticate your requests to the ZoomEye API
1182. **Python Environment**
119   
120   - Python 3.10 or higher is required
121   - Alternatively, you can use Docker to run the server without installing Python
122 
123## Installation
124 
125### Using PIP
126 
127Alternatively, you can install `mcp-server-zoomeye` via pip:
128 
129```bash
130pip install mcp-server-zoomeye
131```
132 
133After installation, you can run it as a script using the following command:
134 
135```bash
136python -m mcp_server_zoomeye
137```
138 
139### Using Docker
140 
141You can also run the ZoomEye MCP server using Docker:
142 
143#### Pull from Docker Hub
144 
145```bash
146# Pull the latest image
147docker pull zoomeyeteam/mcp-server-zoomeye:latest
148 
149# Run the container with your API key
150docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest
151```
152 
153> **Note**: We provide multi-architecture Docker images that support `linux/amd64` and `linux/arm64` platforms and can run on Intel/AMD and ARM (such as Apple Silicon) processors.
154 
155#### Build from Source
156 
157Alternatively, you can build the Docker image from source:
158 
159```bash
160# Clone the repository
161git clone https://github.com/zoomeye-ai/mcp_zoomeye.git
162cd mcp_zoomeye
163 
164# Build the Docker image
165docker build -t zoomeyeteam/mcp-server-zoomeye:local .
166 
167# Run the container
168docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:local
169```
170 
171### Using uv
172 
173[`uv`](https://docs.astral.sh/uv/) is a fast Python package installer and resolver written in Rust. It's a modern alternative to pip that offers significant performance improvements.
174 
175#### Installation of uv
176 
177```bash
178# Install uv using curl (macOS/Linux)
179curl -LsSf https://astral.sh/uv/install.sh | sh
180 
181# Or using PowerShell (Windows)
182irm https://astral.sh/uv/install.ps1 | iex
183 
184# Or using Homebrew (macOS)
185brew install uv
186```
187 
188#### Using uvx to run mcp-server-zoomeye
189 
190No specific installation is required when using [`uvx`](https://docs.astral.sh/uv/guides/tools/), which allows you to run Python packages directly:
191 
192#### Installing with uv
193 
194Alternatively, you can install the package using uv:
195 
196```bash
197# Install in the current environment
198uv pip install mcp-server-zoomeye
199 
200# Or create and install in a new virtual environment
201uv venv
202uv pip install mcp-server-zoomeye
203```
204 
205## Configuration
206 
207### Environment Variables
208 
209The ZoomEye MCP server requires the following environment variable:
210 
211- `ZOOMEYE_API_KEY`: Your ZoomEye API key for authentication
212 
213You can set this environment variable in several ways:
214 
2151. **Export in your shell session**:
216   
217   ```bash
218   export ZOOMEYE_API_KEY="your_api_key_here"
219   ```
2202. **Pass directly when running the container** (for Docker):
221   
222   ```bash
223   docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest
224   ```
225 
226### Configure Claude.app
227 
228Add the following in Claude settings:
229 
230<details>
231<summary>Using uvx</summary>
232 
233```json
234"mcpServers": {
235  "zoomeye": {
236    "command": "uvx",
237    "args": ["mcp-server-zoomeye"],
238    "env": {
239        "ZOOMEYE_API_KEY": "your_api_key_here"
240    }
241  }
242}
243```
244 
245</details>
246 
247<details>
248<summary>Using docker</summary>
249 
250```json
251"mcpServers": {
252  "zoomeye": {
253    "command": "docker",
254    "args": ["run", "-i", "--rm", "-e", "ZOOMEYE_API_KEY=your_api_key_here", "zoomeyeteam/mcp-server-zoomeye:latest"],
255    "env": {
256      "ZOOMEYE_API_KEY": "your_api_key_here"
257    }
258  }
259}
260```
261 
262</details>
263 
264<details>
265<summary>Installed via pip</summary>
266 
267```json
268"mcpServers": {
269  "zoomeye": {
270    "command": "python",
271    "args": ["-m", "mcp_server_zoomeye"],
272    "env": {
273        "ZOOMEYE_API_KEY": "your_api_key_here"
274    }
275  }
276}
277```
278 
279</details>
280 
281### Configure Zed
282 
283Add the following in Zed's settings.json:
284 
285<details>
286<summary>Using uvx</summary>
287 
288```json
289"context_servers": [
290  "mcp-server-zoomeye": {
291    "command": "uvx",
292    "args": ["mcp-server-zoomeye"],
293    "env": {
294        "ZOOMEYE_API_KEY": "your_api_key_here"
295    }
296  }
297],
298```
299 
300</details>
301 
302<details>
303<summary>Installed via pip</summary>
304 
305```json
306"context_servers": {
307  "mcp-server-zoomeye": {
308    "command": "python",
309    "args": ["-m", "mcp_server_zoomeye"],
310    "env": {
311        "ZOOMEYE_API_KEY": "your_api_key_here"
312    }
313  }
314},
315```
316 
317</details>
318 
319## Example Interactions
320 
321### Example 1: Retrieve global Apache Tomcat assets
322 
323```json
324{
325  "name": "zoomeye_search",
326  "arguments": {
327    "qbase64": "app=\"Apache Tomcat\""
328  }
329}
330```
331 
332Response:
333 
334```json
335{
336  "code": 60000,
337  "message": "success",
338  "total": 163139107,
339  "query": "app=\"Apache Tomcat\"",
340  "data": [
341    {
342      "url": "https://1.1.1.1:443",
343      "ssl.jarm": "29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa",
344      "ssl.ja3s": "45094d08156d110d8ee97b204143db14",
345      "iconhash_md5": "f3418a443e7d841097c714d69ec4bcb8",
346      "robots_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
347      "security_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
348      "ip": "1.1.1.1",
349      "domain": "www.google.com",
350      "hostname": "SPACEX",
351      "os": "windows",
352      "port": 443,
353      "service": "https",
354      "title": ["GoogleGoogle appsGoogle Search"],
355      "version": "1.1.0",
356      "device": "webcam",
357      "rdns": "c01031-001.cust.wallcloud.ch",
358      "product": "OpenSSD",
359      "header": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
360      "header_hash": "27f9973fe57298c3b63919259877a84d",
361      "body": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
362      "body_hash": "84a18166fde3ee7e7c974b8d1e7e21b4",
363      "banner": "SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3",
364      "update_time": "2024-07-03T14:34:10",
365      "header.server.name": "nginx",
366      "header.server.version": "1.8.1",
367      "continent.name": "Europe",
368      "country.name": "Germany",
369      "province.name": "Hesse",
370      "city.name": "Frankfurt",
371      "lon": "118.753262",
372      "lat": "32.064838",
373      "isp.name": "aviel.ru",
374      "organization.name": "SERVISFIRST BANK",
375      "zipcode": "210003",
376      "idc": 0,
377      "honeypot": 0,
378      "asn": 4837,
379      "protocol": "tcp",
380      "ssl": "SSL Certificate Version: TLS 1.2 CipherSuit: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256...",
381      "primary_industry": "Finance",
382      "sub_industry": "bank",
383      "rank": 60
384    }
385  ]
386}
387```
388 
389## Debugging and Troubleshooting
390 
391### Using MCP Inspector
392 
393The 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:
394 
395```bash
396# For uvx installation
397npx @modelcontextprotocol/inspector uvx mcp-server-zoomeye
398 
399# If developing locally
400cd path/to/servers/src/mcp_server_zoomeye
401npx @modelcontextprotocol/inspector uv run mcp-server-zoomeye
402```
403 
404### Common Issues
405 
4061. **Authentication Errors**
407   
408   - Ensure your ZoomEye API key is correct and properly set as an environment variable
409   - Check that your API key has not expired or been revoked
4102. **Connection Issues**
411   
412   - Verify your internet connection
413   - Check if the ZoomEye API is experiencing downtime
4143. **No Results**
415   
416   - Your query might be too specific or contain syntax errors
417   - Try simplifying your query or using different search terms
4184. **Rate Limiting**
419   
420   - ZoomEye API has rate limits based on your account type
421   - Space out your requests or upgrade your account for higher limits
422 
423## Advanced Usage
424 
425### Caching
426 
427The ZoomEye MCP server implements caching to improve performance and reduce API calls:
428 
429- Responses are cached based on the query parameters
430- Cache duration is configurable (default: 1 hour)
431- You can bypass the cache by setting `ignore_cache` to `true` in your query
432 
433### Custom Fields
434 
435You can request specific fields in your query results by using the `fields` parameter:
436 
437```json
438{
439  "name": "zoomeye_search",
440  "arguments": {
441    "qbase64": "app=\"Apache\"",
442    "fields": "ip,port,domain,service,os,country,city"
443  }
444}
445```
446 
447### Pagination
448 
449For queries that return many results, you can paginate through them:
450 
451```json
452{
453  "name": "zoomeye_search",
454  "arguments": {
455    "qbase64": "app=\"Apache\"",
456    "page": 2,
457    "pagesize": 20
458  }
459}
460```
461 
462## Contributing
463 
464We 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.
465 
466For examples of other MCP servers and implementation patterns, see:
467https://github.com/modelcontextprotocol/servers
468 
469Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make mcp-server-zoomeye more robust and practical.
470 
471## License
472 
473mcp-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.
474