Shodan MCP Server

Consulta dispositivos, servicios y vulnerabilidades conectados a internet usando la API de Shodan y la base de datos CVE.

GitHub
51

Documentación

Logo

Servidor MCP de Shodan

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso a la funcionalidad de la API de Shodan y a la base de datos de CVE, permitiendo a los asistentes de IA consultar información sobre dispositivos conectados a Internet, servicios y vulnerabilidades.

Características

Inteligencia de Red

  • Información de Host: Obtén información detallada sobre direcciones IP específicas
  • Capacidades de Búsqueda: Busca en la base de datos de Shodan dispositivos y servicios
  • Escaneo de Redes: Escanea rangos de red (notación CIDR) para dispositivos
  • Información de Certificados SSL: Obtén detalles de certificados SSL para dominios
  • Búsqueda de Dispositivos IoT: Encuentra tipos específicos de dispositivos IoT

Inteligencia de Vulnerabilidades

  • Consulta de CVE: Obtén información detallada sobre vulnerabilidades específicas
  • Búsqueda de Vulnerabilidades: Busca CVEs con filtros avanzados (producto, estado KEV, puntuaciones EPSS)
  • Información de CPE: Obtén datos de Enumeración de Plataforma Común para productos
  • Últimas Vulnerabilidades: Accede a los CVEs más recientes y Vulnerabilidades Explotadas Conocidas
  • Predicción de Explotación: Obtén CVEs ordenados por puntuaciones de predicción de explotación EPSS
  • Búsqueda de Exploits: Busca en la base de datos de Exploits de Shodan exploits vinculados a CVE
  • Consulta InternetDB: Consulta de host gratuita sin clave de API (puertos abiertos, nombres de host, CPEs, vulnerabilidades, etiquetas)

Monitoreo de Red

  • Alertas de Red: Crea, lista, inspecciona y elimina alertas persistentes que monitorean IPs/rangos para cambios
  • Notificadores: Lista los proveedores de notificadores disponibles y gestiona notificadores (Slack, correo electrónico, webhook, etc.) a los que las alertas pueden enviar eventos

Instalación

  1. Clona el repositorio:

    git clone https://github.com/Cyreslab-AI/shodan-mcp-server.git
cd shodan-mcp-server

  2. Instala las dependencias:

    npm install

  3. Compila el servidor:

    npm run build

  4. Configura tu clave de API de Shodan:

    export SHODAN_API_KEY="your-api-key-here"

  5. Inicia el servidor:

    npm start

Integración con MCP

Este servidor puede integrarse con Claude u otros asistentes de IA compatibles con MCP. Para añadirlo a Claude Desktop o Claude.app:

  1. Añade el servidor a tu configuración de MCP:

    {
  "mcpServers": {
    "shodan": {
      "command": "node",
      "args": ["/path/to/shodan-mcp-server/build/index.js"],
      "env": {
        "SHODAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

  2. Reinicia Claude para cargar el nuevo servidor MCP.

Herramientas Disponibles

Herramientas de Búsqueda e Información de Host

get_host_info

Obtén información detallada sobre una dirección IP específica.

Parámetros:

  • ip (obligatorio): Dirección IP a consultar
  • max_items (opcional): Número máximo de elementos a incluir en los arrays (por defecto: 5)
  • fields (opcional): Lista de campos a incluir en los resultados (p. ej., ['ip_str', 'ports', 'location.country_name'])

search_shodan

Busca en la base de datos de Shodan dispositivos y servicios.

Parámetros:

  • query (obligatorio): Consulta de búsqueda de Shodan (p. ej., 'apache country:US')
  • page (opcional): Número de página para la paginación de resultados (por defecto: 1)
  • facets (opcional): Lista de facetas a incluir en los resultados de búsqueda (p. ej., ['country', 'org'])
  • max_items (opcional): Número máximo de elementos a incluir en los arrays (por defecto: 5)
  • fields (opcional): Lista de campos a incluir en los resultados (p. ej., ['ip_str', 'ports', 'location.country_name'])
  • summarize (opcional): Si devolver un resumen de los resultados en lugar de los datos completos (por defecto: false)

get_host_count

Obtén el recuento de hosts que coinciden con una consulta de búsqueda sin consumir créditos de consulta.

Parámetros:

  • query (obligatorio): Consulta de búsqueda de Shodan para contar hosts
  • facets (opcional): Lista de facetas a incluir en los resultados del recuento (p. ej., ['country', 'org'])

scan_network_range

Escanea un rango de red (notación CIDR) para dispositivos.

Parámetros:

  • cidr (obligatorio): Rango de red en notación CIDR (p. ej., 192.168.1.0/24)
  • max_items (opcional): Número máximo de elementos a incluir en los resultados (por defecto: 5)
  • fields (opcional): Lista de campos a incluir en los resultados (p. ej., ['ip_str', 'ports', 'location.country_name'])

search_iot_devices

Busca tipos específicos de dispositivos IoT.

Parámetros:

  • device_type (obligatorio): Tipo de dispositivo IoT a buscar (p. ej., 'webcam', 'router', 'smart tv')
  • country (opcional): Código de país opcional para limitar la búsqueda (p. ej., 'US', 'DE')
  • max_items (opcional): Número máximo de elementos a incluir en los resultados (por defecto: 5)

Herramientas SSL y de Certificados

get_ssl_info

Obtén información de certificados SSL para un dominio.

Parámetros:

  • domain (obligatorio): Nombre de dominio para consultar certificados SSL (p. ej., example.com)

Herramientas DNS

dns_lookup

Resuelve nombres de host a direcciones IP mediante consulta DNS.

Parámetros:

  • hostnames (obligatorio): Lista de nombres de host a resolver (p. ej., ['google.com', 'facebook.com'])

reverse_dns_lookup

Obtén nombres de host para direcciones IP mediante consulta DNS inversa.

Parámetros:

  • ips (obligatorio): Lista de direcciones IP a consultar (p. ej., ['8.8.8.8', '1.1.1.1'])

get_domain_info

Obtén información completa del dominio, incluidos subdominios y registros DNS.

Parámetros:

  • domain (obligatorio): Nombre de dominio a consultar (p. ej., 'google.com')
  • history (opcional): Incluir datos DNS históricos (por defecto: false)
  • type (opcional): Filtro de tipo de registro DNS (A, AAAA, CNAME, NS, SOA, MX, TXT)
  • page (opcional): Número de página para la paginación (por defecto: 1)

Herramientas de Utilidad de Búsqueda

list_search_facets

Lista todas las facetas de búsqueda disponibles que se pueden usar con consultas de Shodan.

Parámetros: Ninguno

list_search_filters

Lista todos los filtros de búsqueda disponibles que se pueden usar en consultas de Shodan.

Parámetros: Ninguno

parse_search_tokens

Analiza una consulta de búsqueda para entender qué filtros y parámetros se están utilizando.

Parámetros:

  • query (obligatorio): Consulta de búsqueda de Shodan para analizar

Herramientas de Infraestructura

list_ports

Lista todos los puertos que Shodan rastrea en Internet.

Parámetros: Ninguno

list_protocols

Lista todos los protocolos que se pueden usar al realizar escaneos de Internet bajo demanda.

Parámetros: Ninguno

Herramientas de CVE y Vulnerabilidades

get_cve_info

Obtén información detallada sobre un CVE específico.

Parámetros:

  • cve_id (obligatorio): ID de CVE a consultar (p. ej., 'CVE-2021-44228')

search_cves

Busca vulnerabilidades con varios filtros.

Parámetros:

  • cpe23 (opcional): Cadena CPE 2.3 para buscar (p. ej., 'cpe:2.3:a:apache:log4j:*')
  • product (opcional): Nombre del producto para buscar vulnerabilidades (p. ej., 'apache', 'windows')
  • is_kev (opcional): Filtro para solo Vulnerabilidades Explotadas Conocidas
  • sort_by_epss (opcional): Ordenar resultados por puntuación EPSS (Sistema de Puntuación de Predicción de Explotación)
  • start_date (opcional): Fecha de inicio para filtrar CVEs (formato AAAA-MM-DD)
  • end_date (opcional): Fecha de fin para filtrar CVEs (formato AAAA-MM-DD)
  • limit (opcional): Número máximo de resultados a devolver (por defecto: 10)
  • skip (opcional): Número de resultados a omitir para la paginación (por defecto: 0)

get_cpes

Obtén información de Enumeración de Plataforma Común (CPE) para productos.

Parámetros:

  • product (opcional): Nombre del producto a buscar (p. ej., 'apache', 'windows')
  • vendor (opcional): Nombre del proveedor para filtrar (p. ej., 'microsoft', 'apache')
  • version (opcional): Versión para filtrar (p. ej., '2.4.1')
  • limit (opcional): Número máximo de resultados a devolver (por defecto: 10)
  • skip (opcional): Número de resultados a omitir para la paginación (por defecto: 0)

get_newest_cves

Obtén las vulnerabilidades más recientes de la base de datos de CVE.

Parámetros:

  • limit (opcional): Número máximo de resultados a devolver (por defecto: 10)

get_kev_cves

Obtén Vulnerabilidades Explotadas Conocidas (KEV) de CISA.

Parámetros:

  • limit (opcional): Número máximo de resultados a devolver (por defecto: 10)

get_cves_by_epss

Obtén CVEs ordenados por puntuación EPSS (Sistema de Puntuación de Predicción de Explotación).

Parámetros:

  • limit (opcional): Número máximo de resultados a devolver (por defecto: 10)

get_internetdb_host

Obtén una consulta gratuita y ligera de una dirección IP usando InternetDB de Shodan (puertos abiertos, nombres de host, CPEs, vulnerabilidades, etiquetas). No se requiere clave de API.

Parámetros:

  • ip (obligatorio): Dirección IP a consultar (p. ej., '8.8.8.8')

search_exploits

Busca en la base de datos de Exploits de Shodan (Exploit-DB, Metasploit, exploits vinculados a CVE) exploits conocidos.

Parámetros:

  • query (obligatorio): Consulta de búsqueda de exploits (p. ej., 'apache cve:2021-44228')
  • page (opcional): Número de página para la paginación de resultados (por defecto: 1)
  • facets (opcional): Lista de facetas a incluir en los resultados (p. ej., ['type', 'platform'])

Nota: Al momento de escribir esto, el host exploits.shodan.io ascendente redirige a cvedb.shodan.io y ya no sirve esta API. La herramienta detecta esto y devuelve un objeto {"error": "Unexpected response from the Shodan Exploits API", ...} limpio en lugar de fallar, en caso de que Shodan restaure el endpoint.

count_exploits

Obtén el recuento de exploits que coinciden con una consulta de búsqueda sin devolver los registros completos de exploits.

Parámetros:

  • query (obligatorio): Consulta de búsqueda de exploits para contar resultados
  • facets (opcional): Lista de facetas a incluir en los resultados del recuento (p. ej., ['type', 'platform'])

Herramientas de Alertas de Red

create_alert

Crea una alerta de red persistente de Shodan que monitorea una o más IPs/rangos y reporta cambios a lo largo del tiempo. Esta no es una acción de solo lectura.

Parámetros:

  • name (obligatorio): Nombre descriptivo para la alerta
  • ip (obligatorio): Lista de IPs o rangos CIDR a monitorear (p. ej., ['1.2.3.4', '10.0.0.0/24'])
  • expires (opcional): Número de segundos que la alerta debe permanecer activa antes de expirar automáticamente (omitir para sin expiración)

list_alerts

Lista todas las alertas de red de Shodan configuradas en la cuenta.

Parámetros:

  • include_expired (opcional): Si incluir alertas expiradas en los resultados (por defecto: true)

get_alert

Obtén detalles sobre una alerta de red específica de Shodan por ID.

Parámetros:

  • alert_id (obligatorio): ID de la alerta a recuperar

delete_alert

Elimina permanentemente una alerta de red de Shodan por ID. Esta es una acción destructiva y no se puede deshacer.

Parámetros:

  • alert_id (obligatorio): ID de la alerta a eliminar

Herramientas de Notificadores

list_notifier_providers

Lista los proveedores de notificadores de Shodan disponibles (p. ej., slack, email, webhook, telegram) y los argumentos que requiere cada uno.

Parámetros: Ninguno

list_notifiers

Lista todos los notificadores de Shodan configurados en la cuenta.

Parámetros: Ninguno

create_notifier

Crea un nuevo notificador de Shodan (p. ej., Slack, correo electrónico, webhook) al que las alertas de red pueden enviar eventos. Esta no es una acción de solo lectura.

Parámetros:

  • provider (obligatorio): Nombre del proveedor del notificador (p. ej., 'slack', 'email', 'webhook', 'telegram'). Usa list_notifier_providers para ver las opciones disponibles.
  • args (obligatorio): Argumentos específicos del proveedor (p. ej., {"webhook_url": "https://..."} para slack)
  • description (opcional): Descripción legible por humanos del notificador

delete_notifier

Elimina permanentemente un notificador de Shodan por ID. Esta es una acción destructiva y no se puede deshacer.

Parámetros:

  • notifier_id (obligatorio): ID del notificador a eliminar

Herramientas de Cuenta y Utilidad

get_api_info

Obtén información sobre tu plan de API, incluidos créditos y límites.

Parámetros: Ninguno

get_account_profile

Obtén información del perfil de la cuenta, incluido el estado de membresía y créditos.

Parámetros: Ninguno

get_my_ip

Obtén tu dirección IP actual tal como se ve desde Internet.

Parámetros: Ninguno

Recursos Disponibles

  • shodan://host/{ip}: Información sobre una dirección IP específica

Limitaciones de la API

Algunos endpoints de la API de Shodan requieren una membresía de pago. Las siguientes características solo están disponibles con una clave de API de Shodan de pago:

  • Funcionalidad de búsqueda (search_shodan, scan_network_range, get_ssl_info, search_iot_devices, get_host_count, get_domain_info)
  • Escaneo de redes
  • Consulta de certificados SSL
  • Búsqueda de dispositivos IoT
  • Búsqueda de exploits (search_exploits, count_exploits)
  • Alertas y notificadores de red (create_alert, list_alerts, get_alert, delete_alert, list_notifier_providers, list_notifiers, create_notifier, delete_notifier)

Nota: La funcionalidad de la base de datos CVE (get_cve_info, search_cves, get_cpes, get_newest_cves, get_kev_cves, get_cves_by_epss) es completamente gratuita y no requiere una suscripción de pago de Shodan.

Nota: get_internetdb_host es completamente gratuito y no requiere una clave API de Shodan en absoluto — consulta directamente el servicio público internetdb.shodan.io. El servidor aún requiere una variable de entorno SHODAN_API_KEY para iniciarse (utilizada por las otras herramientas).

Licencia

MIT

Desarrollado por

Cyreslab.ai

Cita

Si utilizas este proyecto en tu investigación o publicaciones, cítalo de la siguiente manera:

author = {Bassem Abidi and Moudather Chelbi},
title = {Shodan MCP Server},
year = {2025},
howpublished = {https://github.com/Cyreslab-AI/shodan-mcp-server},
note = {Accedido: 2025-06-29}