Servidor MCP de ZoomEye

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona información sobre activos de red según las condiciones de consulta. Este servidor permite que los Modelos de Lenguaje Grande (LLM) obtengan información sobre activos de red consultando ZoomEye mediante dorks y otros parámetros de búsqueda.

Este servidor MCP se integra con asistentes de IA y entornos de desarrollo como Claude Desktop, Cursor, Windsurf, Cline, Continue y Zed, lo que les permite buscar y analizar dispositivos, servicios y vulnerabilidades conectados a Internet a través de interacciones de lenguaje natural.

Características

Consultar ZoomEye para obtener información sobre activos de red mediante dorks
Mecanismo de almacenamiento en caché para mejorar el rendimiento y reducir las llamadas a la API
Mecanismo de reintento automático para solicitudes de API fallidas
Manejo y registro de errores integral

Herramientas disponibles

zoomeye_search : obtiene información de activos de red según las condiciones de consulta.
- Parámetros requeridos:
  - qbase64 (cadena): cadena de consulta codificada en Base64 para la búsqueda de ZoomEye
- Parámetros opcionales:
  - page (entero): Ver número de página del activo, el valor predeterminado es 1
  - pagesize (entero): Número de registros por página, el valor predeterminado es 10, el máximo es 1000
  - fields (cadena): Los campos a devolver, separados por comas
  - sub_type (cadena): Tipo de dato, compatible con v4, v6 y web. El valor predeterminado es v4.
  - facets (cadena): elementos estadísticos, separados por comas si hay varios
  - ignore_cache (booleano): si se debe ignorar el caché

Guía de uso

Uso básico

Una vez que el servidor esté en funcionamiento, puedes interactuar con él a través de tu asistente de IA o entorno de desarrollo. Así es como se usa:

Inicie el servidor utilizando uno de los métodos de instalación anteriores
Configura tu asistente de IA (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, etc.) para usar el servidor
Consultar información de la red utilizando lenguaje natural

Guía de sintaxis de búsqueda

El alcance de búsqueda cubre dispositivos (IPv4, IPv6) y sitios web (dominios).
Al ingresar una cadena de búsqueda, el sistema coincidirá con palabras clave en modo "global", incluido el contenido de varios protocolos como HTTP, SSH, FTP, etc. (por ejemplo, encabezados de protocolo HTTP/HTTPS, cuerpo, SSL, título y otros banners de protocolo).
Las cadenas de búsqueda no distinguen entre mayúsculas y minúsculas y se segmentarán para su coincidencia (la página de resultados de búsqueda ofrece una función de prueba de segmentación). Al usar == para la búsqueda, se aplica una coincidencia exacta, distinguiendo entre mayúsculas y minúsculas, con una sintaxis estricta.
Utilice comillas para las cadenas de búsqueda (p. ej., "Sistema Cisco" o 'Sistema Cisco'). Si la cadena de búsqueda contiene comillas, utilice el carácter de escape, p. ej., "a" o "b". Si la cadena de búsqueda contiene paréntesis, utilice el carácter de escape, p. ej., portinfo().

Puede ver reglas de sintaxis de búsqueda más detalladas en prompts.py .

Para obtener más información sobre la API de búsqueda de ZoomEye, consulte la documentación de la API de ZoomEye v2 .

Empezando

Prerrequisitos

Clave API de ZoomEye
- Regístrese para obtener una cuenta en ZoomEye
- Obtén tu clave API desde la configuración de tu cuenta
- La clave API se utilizará para autenticar sus solicitudes a la API de ZoomEye
Entorno de Python
- Se requiere Python 3.10 o superior
- Alternativamente, puede usar Docker para ejecutar el servidor sin instalar Python

Instalación

Uso de PIP

Alternativamente, puede instalar mcp-server-zoomeye a través de pip:

pip install mcp-server-zoomeye

Después de la instalación, puedes ejecutarlo como un script usando el siguiente comando:

python -m mcp_server_zoomeye

Usando Docker

También puede ejecutar el servidor ZoomEye MCP usando Docker:

Extraer desde 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

Nota : Proporcionamos imágenes Docker de múltiples arquitecturas que admiten plataformas linux/amd64 y linux/arm64 y pueden ejecutarse en procesadores Intel/AMD y ARM (como Apple Silicon).

Construir desde la fuente

Alternativamente, puedes crear la imagen de Docker desde la fuente:

# 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

Usando uv

uv es un instalador y solucionador rápido de paquetes de Python escrito en Rust. Es una alternativa moderna a pip que ofrece mejoras significativas de rendimiento.

Instalación de 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

Usando uvx para ejecutar mcp-server-zoomeye

No se requiere ninguna instalación específica al utilizar uvx , lo que le permite ejecutar paquetes de Python directamente:

Instalación con uv

Alternativamente, puede instalar el paquete usando 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

Configuración

Variables de entorno

El servidor ZoomEye MCP requiere la siguiente variable de entorno:

ZOOMEYE_API_KEY : Su clave API de ZoomEye para autenticación

Puede configurar esta variable de entorno de varias maneras:

Exportar en su sesión de shell :
export ZOOMEYE_API_KEY="your_api_key_here"
Pasar directamente al ejecutar el contenedor (para Docker):
docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest

Configurar Claude.app

Agregue lo siguiente en la configuración de 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"
    }
  }
}

Configurar Zed

Agregue lo siguiente en settings.json de Zed:

"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"
    }
  }
},

Ejemplos de interacciones

Ejemplo 1: Recuperar activos globales de Apache Tomcat

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

Respuesta:

{
  "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
    }
  ]
}

Depuración y solución de problemas

Uso del inspector MCP

El Inspector de Protocolo de Contexto de Modelo es una herramienta que ayuda a depurar servidores MCP mediante la simulación de interacciones con el cliente. Puede usarlo para probar su servidor MCP de ZoomEye:

# 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

Problemas comunes

Errores de autenticación
- Asegúrese de que su clave API de ZoomEye sea correcta y esté configurada correctamente como variable de entorno
- Comprueba que tu clave API no haya caducado ni haya sido revocada
Problemas de conexión
- Verificar su conexión a Internet
- Compruebe si la API de ZoomEye está experimentando un tiempo de inactividad
No hay resultados
- Su consulta podría ser demasiado específica o contener errores de sintaxis.
- Intente simplificar su consulta o utilizar términos de búsqueda diferentes.
Limitación de velocidad
- La API de ZoomEye tiene límites de velocidad según el tipo de cuenta
- Distribuya sus solicitudes o actualice su cuenta para obtener límites más altos

Uso avanzado

Almacenamiento en caché

El servidor MCP de ZoomEye implementa el almacenamiento en caché para mejorar el rendimiento y reducir las llamadas API:

Las respuestas se almacenan en caché en función de los parámetros de consulta.
La duración del caché es configurable (predeterminado: 1 hora)
Puede omitir el caché configurando ignore_cache como true en su consulta

Campos personalizados

Puede solicitar campos específicos en los resultados de su consulta utilizando el parámetro fields :

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

Paginación

Para las consultas que devuelven muchos resultados, puede paginarlos:

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

Contribuyendo

Invitamos a contribuir a mcp-server-zoomeye para ampliar y mejorar su funcionalidad. Ya sea añadiendo nuevas herramientas relacionadas, mejorando funciones existentes o mejorando la documentación, su aportación es valiosa.

Para ver ejemplos de otros servidores MCP y patrones de implementación, consulte: https://github.com/modelcontextprotocol/servers

¡Aceptamos solicitudes de incorporación de cambios! Siéntete libre de contribuir con nuevas ideas, correcciones de errores o mejoras para que mcp-server-zoomeye sea más robusto y práctico.

Licencia

mcp-server-zoomeye está licenciado bajo la Licencia MIT. Esto significa que usted tiene libertad de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más información, consulte el archivo de LICENCIA en el repositorio del proyecto.

ZoomEye MCP Server

Integrations