Skip to content
Back to search

mcp_zoomeye

A Model Context Protocol server that provides network asset information based on query conditions. This server allows LLMs to obtain network asset information and supports querying network asset information by zoomeye dork etc.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zoomeye-ai--mcp-zoomeye/badge.svg)](/listings/zoomeye-ai--mcp-zoomeye)

HTML

<a href="/listings/zoomeye-ai--mcp-zoomeye"><img src="/api/listings/zoomeye-ai--mcp-zoomeye/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Using PIP

Alternatively, you can install `mcp-server-zoomeye` via pip:

pip install mcp-server-zoomeye

After installation, you can run it as a script using the following command:

python -m mcp_server_zoomeye

Using Docker

You can also run the ZoomEye MCP server using Docker:

Pull from Docker Hub

# 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

> **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.

Build from Source

Alternatively, you can build the Docker image from source:

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

# Build the Docker image
docker build -t zoomeyeteam/mcp-server-zoomeye:local .

# Run the container
docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:local

Using uv

[`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.

Installation of uv

# Install uv using curl (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using PowerShell (Windows)
irm https://astral.sh/uv/install.ps1 | iex

# Or using Homebrew (macOS)
brew install uv

Using uvx to run mcp-server-zoomeye

No specific installation is required when using [`uvx`](https://docs.astral.sh/uv/guides/tools/), which allows you to run Python packages directly:

Installing with uv

Alternatively, you can install the package using uv:

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

# Or create and install in a new virtual environment
uv venv
uv pip install mcp-server-zoomeye

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 473 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.