{"id":29229430,"url":"https://github.com/knownsec/mcp_zoomeye_org","last_synced_at":"2025-07-06T15:01:42.291Z","repository":{"id":302610213,"uuid":"1010964162","full_name":"knownsec/mcp_zoomeye_org","owner":"knownsec","description":"钟馗之眼(ZoomEye) MCP 服务","archived":false,"fork":false,"pushed_at":"2025-07-03T08:57:26.000Z","size":1339,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-03T09:39:07.658Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knownsec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-30T05:26:33.000Z","updated_at":"2025-07-03T08:57:31.000Z","dependencies_parsed_at":"2025-07-03T09:39:08.906Z","dependency_job_id":"8512676a-ad60-4c7b-8389-26cba902f93c","html_url":"https://github.com/knownsec/mcp_zoomeye_org","commit_stats":null,"previous_names":["knownsec/mcp_zoomeye_org"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/knownsec/mcp_zoomeye_org","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knownsec%2Fmcp_zoomeye_org","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knownsec%2Fmcp_zoomeye_org/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knownsec%2Fmcp_zoomeye_org/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knownsec%2Fmcp_zoomeye_org/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knownsec","download_url":"https://codeload.github.com/knownsec/mcp_zoomeye_org/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knownsec%2Fmcp_zoomeye_org/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263322856,"owners_count":23448719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-03T12:07:29.495Z","updated_at":"2025-07-03T12:07:34.321Z","avatar_url":"https://github.com/knownsec.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \n  \u003ca href=\"https://github.com/knownsec/mcp_zoomeye_org/blob/main/README.md\"\u003e`English`\u003c/a\u003e •\n  \u003ca href=\"https://github.com/knownsec/mcp_zoomeye_org/blob/main/README_zh.md\"\u003e`中文`\u003c/a\u003e \n  \n\u003c/div\u003e\n\n# 🚀 ZoomEye MCP Server\n\nA 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.\n\n## 🔔 Announcement\n\n🎉 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.\n\n🔧 Fully compatible with leading MCP environments:\n\n- Claude Desktop\n- Cursor\n- Windsurf\n- Cline\n- Continue\n- Zed\n- Cherry Studio\n- Chatbox\n\n## 🔑 How can I get a ZoomEye API key?\n\nTo use this MCP server, you’ll need a ZoomEye API key.\n\n1. Go to https://www.zoomeye.org\n2. Register or log in\n3. Click your avatar → **Profile**\n4. Copy your **API-KEY**\n5. Set the environment variable:\n\n   `export ZOOMEYE_API_KEY=\"your_api_key_here\"`\n\n![zoomeye1](./zoomeye1.png)\n\n![zoomeye2](./zoomeye2.png)\n\n## Features\n\n- Query ZoomEye for network asset information using dorks\n- Caching mechanism to improve performance and reduce API calls\n- Automatic retry mechanism for failed API requests\n- Comprehensive error handling and logging\n\n## Available Tools\n\n- `zoomeye_search` - Get network asset information based on query conditions.\n    - Required parameters:\n        - `qbase64` (string): Base64 encoded query string for ZoomEye search\n    - Optional parameters:\n        - `page` (integer): View asset page number, default is 1\n        - `pagesize` (integer): Number of records per page, default is 10, maximum is 1000\n        - `fields` (string): The fields to return, separated by commas\n        - `sub_type` (string): Data type, supports v4, v6, and web. Default is v4\n        - `facets` (string): Statistical items, separated by commas if there are multiple\n        - `ignore_cache` (boolean): Whether to ignore the cache\n\n## Usage Guide\n\n### Basic Usage\n\nOnce the server is running, you can interact with it through your AI assistant or development environment. Here's how to use it:\n\n1. **Start the server** using one of the installation methods above\n2. **Configure your AI assistant** (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, etc.) to use the server\n3. **Query network information** using natural language\n\n![searchexample](example.png)\n\n### Search Syntax Guide\n\n- Search Scope covers devices (IPv4, IPv6) and websites (domains).\n- When entering a search string, the system will match keywords in \"global\" mode, including content from various\n  protocols such as HTTP, SSH, FTP, etc. (e.g., HTTP/HTTPS protocol headers, body, SSL, title, and other protocol\n  banners).\n- Search strings are case-insensitive and will be segmented for matching (the search results page provides a \"\n  segmentation\" test feature). When using == for search, it enforces exact case-sensitive matching with strict syntax.\n- Please use quotes for search strings (e.g., \"Cisco System\" or 'Cisco System'). If the search string contains quotes,\n  use the escape character, e.g.,\"a\\\"b\". If the search string contains parentheses, use the escape character, e.g.,\n  portinfo\\(\\).\n\nYou can see more detailed search syntax rules in [prompts.py](src/mcp_zoomeye_org/prompts.py).\n\nFor more information on the ZoomEye Search API, refer to the [ZoomEye API v2 documentation](https://www.zoomeye.org/doc).\n\n## Getting Started\n\n### Prerequisites\n\n1. **ZoomEye API Key**\n\n    - Register for an account at [ZoomEye](https://www.zoomeye.org/)\n    - Obtain your API key from your account settings\n    - The API key will be used to authenticate your requests to the ZoomEye API\n2. **Python Environment**\n\n    - Python 3.10 or higher is required\n    - Alternatively, you can use Docker to run the server without installing Python\n\n## Installation\n\n### Using PIP\n\nAlternatively, you can install `mcp-zoomeye-org` via pip:\n\n```bash\npip install mcp-zoomeye-org\n```\n\nAfter installation, you can run it as a script using the following command:\n\n```bash\npython -m mcp_zoomeye_org\n```\n\n### Using uv\n\n[`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.\n\n#### Installation of uv\n\n```bash\n# Install uv using curl (macOS/Linux)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Or using PowerShell (Windows)\nirm https://astral.sh/uv/install.ps1 | iex\n\n# Or using Homebrew (macOS)\nbrew install uv\n```\n\n#### Using uvx to run mcp-zoomeye-org\n\nNo specific installation is required when using [`uvx`](https://docs.astral.sh/uv/guides/tools/), which allows you to run Python packages directly:\n\n#### Installing with uv\n\nAlternatively, you can install the package using uv:\n\n```bash\n# Install in the current environment\nuv pip install mcp-zoomeye-org\n\n# Or create and install in a new virtual environment\nuv venv\nuv pip install mcp-zoomeye-org\n```\n\n## Configuration\n\n### Environment Variables\n\nThe ZoomEye MCP server requires the following environment variable:\n\n- `ZOOMEYE_API_KEY`: Your ZoomEye API key for authentication\n\nYou can set this environment variable in several ways:\n\n1. **Export in your shell session**:\n\n   ```bash\n   export ZOOMEYE_API_KEY=\"your_api_key_here\"\n   ```\n\n### Configure Claude.app\n\nAdd the following in Claude settings:\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing uvx\u003c/summary\u003e\n\n```json\n\"mcpServers\": {\n\"zoomeye\": {\n\"command\": \"uvx\",\n\"args\": [\"mcp-zoomeye-org\"],\n\"env\": {\n\"ZOOMEYE_API_KEY\": \"your_api_key_here\"\n}\n}\n}\n```\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eInstalled via pip\u003c/summary\u003e\n\n```json\n\"mcpServers\": {\n\"zoomeye\": {\n\"command\": \"python\",\n\"args\": [\"-m\", \"mcp_server_zoomeye\"],\n\"env\": {\n\"ZOOMEYE_API_KEY\": \"your_api_key_here\"\n}\n}\n}\n```\n\n\u003c/details\u003e\n\n### Configure Zed\n\nAdd the following in Zed's settings.json:\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing uvx\u003c/summary\u003e\n\n```json\n\"context_servers\": [\n\"mcp-zoomeye-org\": {\n\"command\": \"uvx\",\n\"args\": [\"mcp-zoomeye-org\"],\n\"env\": {\n\"ZOOMEYE_API_KEY\": \"your_api_key_here\"\n}\n}\n],\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstalled via pip\u003c/summary\u003e\n\n```json\n\"context_servers\": {\n\"mcp-zoomeye-org\": {\n\"command\": \"python\",\n\"args\": [\"-m\", \"mcp_server_zoomeye\"],\n\"env\": {\n\"ZOOMEYE_API_KEY\": \"your_api_key_here\"\n}\n}\n},\n```\n\n\u003c/details\u003e\n\n## Example Interactions\n\n### Example 1: Retrieve global Apache Tomcat assets\n\n```json\n{\n  \"name\": \"zoomeye_search\",\n  \"arguments\": {\n    \"qbase64\": \"app=\\\"Apache Tomcat\\\"\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"code\": 60000,\n  \"message\": \"success\",\n  \"total\": 163139107,\n  \"query\": \"app=\\\"Apache Tomcat\\\"\",\n  \"data\": [\n    {\n      \"url\": \"https://1.1.1.1:443\",\n      \"ssl.jarm\": \"29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa\",\n      \"ssl.ja3s\": \"45094d08156d110d8ee97b204143db14\",\n      \"iconhash_md5\": \"f3418a443e7d841097c714d69ec4bcb8\",\n      \"robots_md5\": \"0b5ce08db7fb8fffe4e14d05588d49d9\",\n      \"security_md5\": \"0b5ce08db7fb8fffe4e14d05588d49d9\",\n      \"ip\": \"1.1.1.1\",\n      \"domain\": \"www.google.com\",\n      \"hostname\": \"SPACEX\",\n      \"os\": \"windows\",\n      \"port\": 443,\n      \"service\": \"https\",\n      \"title\": [\"GoogleGoogle appsGoogle Search\"],\n      \"version\": \"1.1.0\",\n      \"device\": \"webcam\",\n      \"rdns\": \"c01031-001.cust.wallcloud.ch\",\n      \"product\": \"OpenSSD\",\n      \"header\": \"HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...\",\n      \"header_hash\": \"27f9973fe57298c3b63919259877a84d\",\n      \"body\": \"HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...\",\n      \"body_hash\": \"84a18166fde3ee7e7c974b8d1e7e21b4\",\n      \"banner\": \"SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3\",\n      \"update_time\": \"2024-07-03T14:34:10\",\n      \"header.server.name\": \"nginx\",\n      \"header.server.version\": \"1.8.1\",\n      \"continent.name\": \"Europe\",\n      \"country.name\": \"Germany\",\n      \"province.name\": \"Hesse\",\n      \"city.name\": \"Frankfurt\",\n      \"lon\": \"118.753262\",\n      \"lat\": \"32.064838\",\n      \"isp.name\": \"aviel.ru\",\n      \"organization.name\": \"SERVISFIRST BANK\",\n      \"zipcode\": \"210003\",\n      \"idc\": 0,\n      \"honeypot\": 0,\n      \"asn\": 4837,\n      \"protocol\": \"tcp\",\n      \"ssl\": \"SSL Certificate Version: TLS 1.2 CipherSuit: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256...\",\n      \"primary_industry\": \"Finance\",\n      \"sub_industry\": \"bank\",\n      \"rank\": 60\n    }\n  ]\n}\n```\n\n## Debugging and Troubleshooting\n\n### Using MCP Inspector\n\nThe 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:\n\n```bash\n# For uvx installation\nnpx @modelcontextprotocol/inspector uvx mcp-zoomeye-org\n\n# If developing locally\ncd path/to/servers/src/mcp_server_zoomeye\nnpx @modelcontextprotocol/inspector uv run mcp-zoomeye-org\n```\n\n### Common Issues\n\n1. **Authentication Errors**\n\n    - Ensure your ZoomEye API key is correct and properly set as an environment variable\n    - Check that your API key has not expired or been revoked\n2. **Connection Issues**\n\n    - Verify your internet connection\n    - Check if the ZoomEye API is experiencing downtime\n3. **No Results**\n\n    - Your query might be too specific or contain syntax errors\n    - Try simplifying your query or using different search terms\n4. **Rate Limiting**\n\n    - ZoomEye API has rate limits based on your account type\n    - Space out your requests or upgrade your account for higher limits\n\n## Advanced Usage\n\n### Caching\n\nThe ZoomEye MCP server implements caching to improve performance and reduce API calls:\n\n- Responses are cached based on the query parameters\n- Cache duration is configurable (default: 1 hour)\n- You can bypass the cache by setting `ignore_cache` to `true` in your query\n\n### Custom Fields\n\nYou can request specific fields in your query results by using the `fields` parameter:\n\n```json\n{\n  \"name\": \"zoomeye_search\",\n  \"arguments\": {\n    \"qbase64\": \"app=\\\"Apache\\\"\",\n    \"fields\": \"ip,port,domain,service,os,country,city\"\n  }\n}\n```\n\n### Pagination\n\nFor queries that return many results, you can paginate through them:\n\n```json\n{\n  \"name\": \"zoomeye_search\",\n  \"arguments\": {\n    \"qbase64\": \"app=\\\"Apache\\\"\",\n    \"page\": 2,\n    \"pagesize\": 20\n  }\n}\n```\n\n## Contributing\n\nWe encourage contributions to mcp-zoomeye-org to help expand and improve its functionality. Whether it's adding new related tools, enhancing existing features, or improving documentation, your input is valuable.\n\nFor examples of other MCP servers and implementation patterns, see:\nhttps://github.com/modelcontextprotocol/servers\n\nPull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make mcp-zoomeye-org more robust and practical.\n\n## License\n\nmcp-zoomeye-org 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknownsec%2Fmcp_zoomeye_org","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknownsec%2Fmcp_zoomeye_org","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknownsec%2Fmcp_zoomeye_org/lists"}