Skip to main content
Glama
enesjakozh
zoomeye-ai

ZoomEye MCP Server

Official
by zoomeye-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

ZoomEye MCP 서버

쿼리 조건에 따라 네트워크 자산 정보를 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 통해 대규모 언어 모델(LLM)은 dork 및 기타 검색 매개변수를 사용하여 ZoomEye에 쿼리를 보내 네트워크 자산 정보를 얻을 수 있습니다.

이 MCP 서버는 Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed와 같은 AI 어시스턴트 및 개발 환경과 통합되어 자연어 상호 작용을 통해 인터넷에 연결된 장치, 서비스 및 취약점을 검색하고 분석할 수 있습니다.

특징

  • dork를 사용하여 ZoomEye에서 네트워크 자산 정보 쿼리

  • 성능 향상 및 API 호출 감소를 위한 캐싱 메커니즘

  • 실패한 API 요청에 대한 자동 재시도 메커니즘

  • 포괄적인 오류 처리 및 로깅

Related MCP server: Shodan-MCP-Server

사용 가능한 도구

  • zoomeye_search - 쿼리 조건에 따라 네트워크 자산 정보를 가져옵니다.

    • 필수 매개변수:

      • qbase64 (문자열): ZoomEye 검색을 위한 Base64 인코딩된 쿼리 문자열

    • 선택 매개변수:

      • page (정수): 자산 페이지 번호 보기, 기본값은 1입니다.

      • pagesize (정수): 페이지당 레코드 수, 기본값은 10, 최대값은 1000입니다.

      • fields (문자열): 쉼표로 구분된 반환할 필드

      • sub_type (문자열): 데이터 유형이며 v4, v6 및 웹을 지원합니다. 기본값은 v4입니다.

      • facets (문자열): 통계 항목(여러 개가 있는 경우 쉼표로 구분)

      • ignore_cache (부울): 캐시를 무시할지 여부

사용 가이드

기본 사용법

서버가 실행되면 AI 어시스턴트나 개발 환경을 통해 서버와 상호 작용할 수 있습니다. 사용 방법은 다음과 같습니다.

  1. 위의 설치 방법 중 하나를 사용하여 서버를 시작하세요.

  2. AI 어시스턴트(Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed 등)를 구성하여 서버를 사용하세요.

  3. 자연어를 사용하여 네트워크 정보 쿼리

검색예시

검색 구문 가이드

  • 검색 범위에는 장치(IPv4, IPv6)와 웹사이트(도메인)가 포함됩니다.

  • 검색어를 입력하면 시스템은 HTTP, SSH, FTP 등 다양한 프로토콜의 콘텐츠(예: HTTP/HTTPS 프로토콜 헤더, 본문, SSL, 제목 및 기타 프로토콜 배너)를 포함하여 "글로벌" 모드로 키워드를 일치시킵니다.

  • 검색 문자열은 대소문자를 구분하지 않으며, 일치 여부를 확인하기 위해 분할됩니다(검색 결과 페이지에 "분할" 테스트 기능이 제공됩니다). 검색에 ==를 사용하면 엄격한 구문을 사용하여 대소문자를 정확하게 구분하여 일치시킵니다.

  • 검색 문자열에는 따옴표를 사용해 주세요(예: "Cisco System" 또는 'Cisco System'). 검색 문자열에 따옴표가 포함된 경우 이스케이프 문자를 사용하세요(예: "a"b"). 검색 문자열에 괄호가 포함된 경우 이스케이프 문자를 사용하세요(예: portinfo()).

prompts.py 에서 더 자세한 검색 구문 규칙을 볼 수 있습니다.

ZoomEye 검색 API에 대한 자세한 내용은 ZoomEye API v2 설명서를 참조하세요.

시작하기

필수 조건

  1. ZoomEye API 키

    • ZoomEye 에 계정을 등록하세요

    • 계정 설정에서 API 키를 받으세요

    • API 키는 ZoomEye API에 대한 요청을 인증하는 데 사용됩니다.

  2. 파이썬 환경

    • Python 3.10 이상이 필요합니다

    • 또는 Python을 설치하지 않고도 Docker를 사용하여 서버를 실행할 수 있습니다.

설치

PIP 사용

또는 pip를 통해 mcp-server-zoomeye 설치할 수 있습니다.

지엑스피1

설치 후 다음 명령을 사용하여 스크립트로 실행할 수 있습니다.

python -m mcp_server_zoomeye

Docker 사용

Docker를 사용하여 ZoomEye MCP 서버를 실행할 수도 있습니다.

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

참고 : linux/amd64 및 linux/arm64 플랫폼을 지원하고 Intel/AMD 및 ARM(예: Apple Silicon) 프로세서에서 실행할 수 있는 다중 아키텍처 Docker 이미지를 제공합니다.

소스에서 빌드

또는 소스에서 Docker 이미지를 빌드할 수 있습니다.

# 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

uv를 사용하여

uv 는 Rust로 작성된 빠른 Python 패키지 설치 및 해결 프로그램입니다. pip의 현대적인 대안으로, 상당한 성능 향상을 제공합니다.

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

uvx를 사용하여 mcp-server-zoomeye 실행

uvx 사용하면 특별한 설치가 필요하지 않으므로 Python 패키지를 직접 실행할 수 있습니다.

uv로 설치하기

또는 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

구성

환경 변수

ZoomEye MCP 서버에는 다음 환경 변수가 필요합니다.

  • ZOOMEYE_API_KEY : 인증을 위한 ZoomEye API 키

이 환경 변수는 여러 가지 방법으로 설정할 수 있습니다.

  1. 셸 세션에서 내보내기 :

    export ZOOMEYE_API_KEY="your_api_key_here"

  2. 컨테이너를 실행할 때 직접 전달합니다 (Docker의 경우):

    docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest

Claude.app 구성

Claude 설정에 다음을 추가합니다.

"mcpServers": {
  "zoomeye": {
    "command": "uvx",
    "args": ["mcp-server-zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
}
"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"
    }
  }
}
"mcpServers": {
  "zoomeye": {
    "command": "python",
    "args": ["-m", "mcp_server_zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
}

Zed 구성

Zed의 settings.json에 다음을 추가하세요.

"context_servers": [
  "mcp-server-zoomeye": {
    "command": "uvx",
    "args": ["mcp-server-zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
],
"context_servers": {
  "mcp-server-zoomeye": {
    "command": "python",
    "args": ["-m", "mcp_server_zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
},

예시 상호작용

예제 1: 글로벌 Apache Tomcat 자산 검색

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

응답:

{
  "code": 60000,
  "message": "success",
  "total": 163139107,
  "query": "title=\"cisco vpn\"",
  "data": [
    {
      "url": "https://1.1.1.1:443",
      "ssl.jarm": "29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa",
      "ssl.ja3s": "45094d08156d110d8ee97b204143db14",
      "iconhash_md5": "f3418a443e7d841097c714d69ec4bcb8",
      "robots_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
      "security_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
      "ip": "1.1.1.1",
      "domain": "www.google.com",
      "hostname": "SPACEX",
      "os": "windows",
      "port": 443,
      "service": "https",
      "title": ["GoogleGoogle appsGoogle Search"],
      "version": "1.1.0",
      "device": "webcam",
      "rdns": "c01031-001.cust.wallcloud.ch",
      "product": "OpenSSD",
      "header": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
      "header_hash": "27f9973fe57298c3b63919259877a84d",
      "body": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
      "body_hash": "84a18166fde3ee7e7c974b8d1e7e21b4",
      "banner": "SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3",
      "update_time": "2024-07-03T14:34:10",
      "header.server.name": "nginx",
      "header.server.version": "1.8.1",
      "continent.name": "Europe",
      "country.name": "Germany",
      "province.name": "Hesse",
      "city.name": "Frankfurt",
      "lon": "118.753262",
      "lat": "32.064838",
      "isp.name": "aviel.ru",
      "organization.name": "SERVISFIRST BANK",
      "zipcode": "210003",
      "idc": 0,
      "honeypot": 0,
      "asn": 4837,
      "protocol": "tcp",
      "ssl": "SSL Certificate Version: TLS 1.2 CipherSuit: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256...",
      "primary_industry": "Finance",
      "sub_industry": "bank",
      "rank": 60
    }
  ]
}

디버깅 및 문제 해결

MCP Inspector 사용

모델 컨텍스트 프로토콜 검사기는 클라이언트 상호작용을 시뮬레이션하여 MCP 서버 디버깅을 지원하는 도구입니다. ZoomEye MCP 서버를 테스트하는 데 사용할 수 있습니다.

# 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

일반적인 문제

  1. 인증 오류

    • ZoomEye API 키가 올바르고 환경 변수로 올바르게 설정되었는지 확인하세요.

    • API 키가 만료되거나 취소되지 않았는지 확인하세요.

  2. 연결 문제

    • 인터넷 연결을 확인하세요

    • ZoomEye API가 다운타임을 겪고 있는지 확인하세요

  3. 결과 없음

    • 귀하의 쿼리가 너무 구체적이거나 구문 오류가 포함되어 있을 수 있습니다.

    • 쿼리를 단순화하거나 다른 검색어를 사용해 보세요.

  4. 속도 제한

    • ZoomEye API에는 계정 유형에 따라 요금 제한이 있습니다.

    • 요청 범위를 넓히거나 계정을 업그레이드하여 더 높은 한도를 얻으세요.

고급 사용법

캐싱

ZoomEye MCP 서버는 성능을 개선하고 API 호출을 줄이기 위해 캐싱을 구현합니다.

  • 응답은 쿼리 매개변수를 기반으로 캐시됩니다.

  • 캐시 기간은 구성 가능합니다(기본값: 1시간)

  • 쿼리에서 ignore_cache``true 로 설정하여 캐시를 우회할 수 있습니다.

사용자 정의 필드

fields 매개변수를 사용하여 쿼리 결과에서 특정 필드를 요청할 수 있습니다.

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

쪽수 매기기

많은 결과를 반환하는 쿼리의 경우, 결과를 페이지별로 살펴볼 수 있습니다.

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

기여하다

mcp-server-zoomeye의 기능을 확장하고 개선하는 데 도움이 되도록 기여해 주시기 바랍니다. 새로운 관련 도구를 추가하거나, 기존 기능을 강화하거나, 문서를 개선하는 등 여러분의 의견은 소중합니다.

다른 MCP 서버 및 구현 패턴의 예는 https://github.com/modelcontextprotocol/servers를 참조하세요.

풀 리퀘스트를 환영합니다! mcp-server-zoomeye를 더욱 강력하고 실용적으로 만들기 위한 새로운 아이디어, 버그 수정, 개선 사항을 자유롭게 공유해 주세요.

특허

mcp-server-zoomeye는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 조건에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.

Available Tools

3 tools
zoomeye_vuldb_by_idC

Search for detailed vulnerability information by vulnerability ID and return formatted results.

Use this tool to retrieve comprehensive security vulnerability details from the vulnerability
database using a vulnerability identifier (CVE, CNVD, CNNVD). Results include:
ParametersJSON Schema
NameRequiredDescriptionDefault
cve_idYesA valid vulnerability identifier, eg: CVE-XXXX-XXXX,CNVD-XXXX-XXXX,CNNVD-XXXX-XXXX

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavioral traits. It indicates a read-only operation (search/retrieve), but fails to describe output format, pagination, rate limits, or any side effects. The abrupt end ('Results include:') leaves the agent guessing what the tool returns, which is a significant gap for transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, but it is incomplete, ending with 'Results include:' without any continuation. This disrupts the structure and leaves the description unfinished. Every sentence should be complete and purposeful, and this one fails to deliver its intended content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should explain the return values comprehensively. It starts listing results but cuts off, providing zero information about what the formatted results contain. This is a major omission for a tool that only has one parameter and no other documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, with the parameter 'cve_id' described and examples given. The description repeats this information without adding substantial new meaning. Baseline is 3, and since no extra semantics are provided, the score remains at 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search for detailed vulnerability information by vulnerability ID', specifying the verb and resource. It lists the accepted ID formats (CVE, CNVD, CNNVD), which helps the agent understand the tool's scope. However, it does not differentiate from sibling tools like 'zoomeye_search' or 'zoomeye_vuldb_by_keyword', and the incomplete sentence 'Results include:' slightly reduces clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'Use this tool to retrieve...' but provides no guidance on when to use it versus alternatives, such as the sibling tool 'zoomeye_vuldb_by_keyword'. There is no mention of prerequisites, limitations, or exclusions, leaving the agent to infer usage context without explicit advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

zoomeye_vuldb_by_keywordA

Search ZoomEye's vulnerability database for security vulnerabilities based on a specified keyword.

This function queries the ZoomEye vulnerability database to retrieve information about known security vulnerabilities associated with specific products, vendors. Results include vulnerability details such as CVE IDs, severity ratings, affected versions, and vulnerability descriptions.

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYesSearch term to query the vulnerability database. This can be a product name, vendor name (e.g., "nginx", "mysql", "tomcat", "WordPress", "hikvision", "huawei").
page_sizeNoNumber of records per page, default is 10, maximum is 100.

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, but the description only lists output fields without behavioral disclosures like read-only guarantee, rate limits, or authentication needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, though the second paragraph could be shortened without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description reasonably explains return fields (CVE, severity, etc.) and implies pagination via page_size, though total count is omitted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description enhances understanding by providing examples for keyword and clarifying page_size defaults/maximum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches ZoomEye's vulnerability database by keyword, and implicitly distinguishes it from siblings (search vs. by ID).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains it retrieves vulnerability info for products/vendors but does not explicitly compare with zoomeye_search or zoomeye_vuldb_by_id.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedzoomeye_search
    • First observedzoomeye_vuldb_by_id
    • First observedzoomeye_vuldb_by_keyword
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool serves a distinct purpose: one for general asset search, one for vulnerability detail by ID, and one for vulnerability keyword search. There is no overlap in functionality.

Naming Consistency5/5

All tools follow a consistent 'zoomeye_' prefix with snake_case naming: search, vuldb_by_id, vuldb_by_keyword. Pattern is uniform and predictable.

Tool Count4/5

With 3 tools, the set is minimal but appropriate for the ZoomEye domain, covering asset search and vulnerability queries. Slightly thin but reasonable given the focused scope.

Completeness3/5

The tools cover basic search and vulnerability lookup, but lack features like retrieving detailed host info, filtering by specific fields, or obtaining result counts. Some operations are missing for full workflow coverage.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-shodan

    w0h1v
    A
    license
    A
    quality
    A
    maintenance
    MCP server for querying the Shodan API and Shodan CVEDB. This server provides tools for IP lookups, device searches, DNS lookups, vulnerability queries, CPE lookups, and more.
    7
    362 npm
    174
    MIT

  • Shodan-MCP-Server

    X3r0K
    F
    license
    Not graded
    quality
    D
    maintenance
    This is a Model Context Protocol (MCP) server that provides access to the Shodan API. It allows you to programmatically query Shodan for information about devices, vulnerabilities, and more.
    2
    -

  • SurveyHub-MCP

    helGayhub233
    A
    license
    B
    quality
    B
    maintenance
    Aggregates multiple cyberspace search engines (FOFA, Quake, Hunter, ZoomEye) into a unified MCP server, enabling asset search, pagination, statistics, and account info retrieval.
    26
    MIT

Appeared in Searches