Skip to main content
Glama
enesjakozh
w0h1v

mcp-shodan

by w0h1v
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Servidor MCP de Shodan

insignia de herrería

Un servidor de Protocolo de Contexto de Modelo (MCP) para consultar la API y la CVEDB de Shodan . Este servidor proporciona acceso completo a los servicios de inteligencia y seguridad de red de Shodan, incluyendo reconocimiento de IP, operaciones DNS, rastreo de vulnerabilidades y descubrimiento de dispositivos. Todas las herramientas proporcionan resultados estructurados y formateados para facilitar el análisis y la integración.

Inicio rápido (recomendado)

Instalación mediante herrería

Para instalar Shodan Server para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install @burtthecoder/mcp-shodan --client claude

Instalación manual

  1. Instalar el servidor globalmente a través de npm:

npm install -g @burtthecoder/mcp-shodan

  1. Agregue a su archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "shodan": {
      "command": "mcp-shodan",
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key"
      }
    }
  }
}

Ubicación del archivo de configuración:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Ventanas: %APPDATA%\Claude\claude_desktop_config.json

  1. Reiniciar Claude Desktop

Related MCP server: Shodan-MCP-Server

Configuración alternativa (de la fuente)

Si prefiere ejecutar desde la fuente o necesita modificar el código:

  1. Clonar y construir:

git clone https://github.com/BurtTheCoder/mcp-shodan.git
cd mcp-shodan
npm install
npm run build

  1. Añade a tu configuración de Claude Desktop:

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

Características

  • Reconocimiento de red : consulta información detallada sobre direcciones IP, incluidos puertos abiertos, servicios y vulnerabilidades

  • Operaciones de DNS : búsquedas DNS directas e inversas para dominios y direcciones IP

  • Inteligencia de vulnerabilidades : acceso a la CVEDB de Shodan para obtener información detallada sobre vulnerabilidades, búsquedas de CPE y seguimiento de CVE específicos del producto.

  • Descubrimiento de dispositivos : busque en la base de datos de Shodan de dispositivos conectados a Internet con filtrado avanzado

Herramientas

1. Herramienta de búsqueda de IP

  • Nombre: ip_lookup

  • Descripción: Recupere información completa sobre una dirección IP, incluida la geolocalización, los puertos abiertos, los servicios en ejecución, los certificados SSL, los nombres de host y los detalles del proveedor de la nube si están disponibles.

  • Parámetros:

    • ip (obligatorio): dirección IP a buscar

  • Devoluciones:

    • Información IP (dirección, organización, ISP, ASN)

    • Ubicación (país, ciudad, coordenadas)

    • Servicios (puertos, protocolos, banners)

    • Detalles del proveedor de la nube (si están disponibles)

    • Nombres de host y dominios asociados

    • Etiquetas

2. Herramienta de búsqueda Shodan

  • Nombre: shodan_search

  • Descripción: Busca en la base de datos de dispositivos conectados a Internet de Shodan

  • Parámetros:

    • query (obligatoria): consulta de búsqueda de Shodan

    • max_results (opcional, predeterminado: 10): Número de resultados a devolver

  • Devoluciones:

    • Resumen de búsqueda con resultados totales

    • Estadísticas de distribución por país

    • Información detallada del dispositivo que incluye:

      • Información básica (IP, organización, ISP)

      • Datos de ubicación

      • Detalles del servicio

      • Información del servidor web

      • Nombres de host y dominios asociados

3. Herramienta de búsqueda de CVE

  • Nombre: cve_lookup

  • Descripción: Consulta información detallada sobre vulnerabilidades de la CVEDB de Shodan

  • Parámetros:

    • cve (obligatorio): identificador CVE en formato CVE-AAAA-NNNNN (p. ej., CVE-2021-44228)

  • Devoluciones:

    • Información básica (ID, fecha de publicación, resumen)

    • Puntuaciones de gravedad:

      • CVSS v2 y v3 con niveles de gravedad

      • Probabilidad y clasificación EPSS

    • Evaluación de impacto:

      • Estado de KEV

      • Mitigaciones propuestas

      • Asociaciones de ransomware

    • Productos afectados (CPE)

    • Referencias

4. Herramienta de búsqueda de DNS

  • Nombre: dns_lookup

  • Descripción: Resolver nombres de dominio a direcciones IP utilizando el servicio DNS de Shodan

  • Parámetros:

    • hostnames (obligatorio): Matriz de nombres de host para resolver

  • Devoluciones:

    • Resoluciones DNS que asignan nombres de host a IP

    • Resumen de búsquedas totales y nombres de host consultados

5. Herramienta de búsqueda inversa de DNS

  • Nombre: reverse_dns_lookup

  • Descripción: Realizar búsquedas DNS inversas para encontrar nombres de host asociados con direcciones IP

  • Parámetros:

    • ips (obligatorio): Matriz de direcciones IP para buscar

  • Devoluciones:

    • Resoluciones DNS inversas que asignan IP a nombres de host

    • Resumen de búsquedas totales y resultados

6. Herramienta de búsqueda de CPE

  • Nombre: cpe_lookup

  • Descripción: Busque entradas de Enumeración de plataforma común (CPE) por nombre de producto

  • Parámetros:

    • product (obligatorio): Nombre del producto a buscar

    • count (opcional, predeterminado: falso): si es verdadero, devuelve solo el recuento de CPE coincidentes

    • skip (opcional, predeterminado: 0): Número de CPE a omitir (para paginación)

    • limit (opcional, predeterminado: 1000): número máximo de CPE a devolver

  • Devoluciones:

    • Cuando el recuento es verdadero: Número total de CPE coincidentes

    • Cuando el recuento es falso: Lista de CPE con detalles de paginación

7. Herramienta de CVEs por producto

  • Nombre: cves_by_product

  • Descripción: Búsqueda de vulnerabilidades que afecten a productos o CPE específicos

  • Parámetros:

    • cpe23 (opcional): identificador CPE 2.3 (formato: cpe:2.3:parte:proveedor:producto:versión)

    • product (opcional): Nombre del producto en el que se buscarán CVE

    • count (opcional, valor predeterminado: falso): si es verdadero, devuelve solo el recuento de CVE coincidentes

    • is_kev (opcional, valor predeterminado: falso): si es verdadero, devuelve solo CVE con el indicador KEV establecido

    • sort_by_epss (opcional, predeterminado: falso): si es verdadero, ordena los CVE por puntuación EPSS

    • skip (opcional, predeterminado: 0): Número de CVE a omitir (para paginación)

    • limit (opcional, predeterminado: 1000): número máximo de CVE a devolver

    • start_date (opcional): Fecha de inicio para filtrar CVE (formato: AAAA-MM-DDTHH:MM:SS)

    • end_date (opcional): Fecha de finalización para filtrar CVE (formato: AAAA-MM-DDTHH:MM:SS)

  • Notas:

    • Debe proporcionar cpe23 o producto, pero no ambos

    • El filtrado de fechas utiliza la hora de publicación de los CVE

  • Devoluciones:

    • Información de la consulta

    • Resumen de resultados con detalles de paginación

    • Información detallada sobre vulnerabilidades que incluye:

      • Información básica

      • Puntuaciones de gravedad

      • Evaluaciones de impacto

      • Referencias

Requisitos

Solución de problemas

Problemas con la clave API

Si ve errores relacionados con la clave API (por ejemplo, "La solicitud falló con el código de estado 401"):

  1. Verifique su clave API:

    • Debe ser una clave API de Shodan válida desde la configuración de su cuenta

    • Asegúrese de que la clave tenga suficientes créditos/permisos para la operación

    • Compruebe si hay espacios adicionales o comillas alrededor de la clave en la configuración

    • Verifique que la clave esté configurada correctamente en la variable de entorno SHODAN_API_KEY

  2. Códigos de error comunes:

    • 401 No autorizado: Clave API no válida o autenticación faltante

    • 402 Pago requerido: créditos fuera de consulta

    • 429 Demasiadas solicitudes: Límite de velocidad excedido

  3. Pasos de configuración: a. Obtén tu clave API de la cuenta de Shodan. b. Añádela a tu archivo de configuración.

    {
  "mcpServers": {
    "shodan": {
      "command": "mcp-shodan",
      "env": {
        "SHODAN_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

    c. Guarde el archivo de configuración. d. Reinicie Claude Desktop.

  4. Probando su clave:

    • Pruebe primero una consulta sencilla (por ejemplo, dns_lookup para "google.com")

    • Consulta el panel de tu cuenta de Shodan para conocer el estado del crédito

    • Verifique que la clave funcione directamente con curl:

      curl "https://api.shodan.io/dns/resolve?hostnames=google.com&key=your-api-key"

Problemas de carga del módulo

Si ve errores de carga del módulo:

  1. Para la instalación global: utilice la configuración simple que se muestra en Inicio rápido

  2. Para la instalación de origen: asegúrese de estar utilizando Node.js v18 o posterior

Desarrollo

Para ejecutar en modo de desarrollo con recarga en caliente:

npm run dev

Manejo de errores

El servidor incluye un manejo integral de errores para:

  • Claves API no válidas

  • Limitación de velocidad

  • Errores de red

  • Parámetros de entrada no válidos

  • Formatos CVE no válidos

  • Parámetros de búsqueda de CPE no válidos

  • Formatos de fecha no válidos

  • Validación de parámetros mutuamente excluyentes

Historial de versiones

  • v1.0.12: Se agregó búsqueda DNS inversa y se mejoró el formato de salida

  • v1.0.7: Se agregó la funcionalidad de búsqueda de CVE por producto y se cambió el nombre de la herramienta de vulnerabilidades a cve_lookup

  • v1.0.6: Se agregó integración con CVEDB para mejorar las búsquedas de CVE y la funcionalidad de búsqueda de CPE

  • v1.0.0: Versión inicial con funcionalidad principal

Contribuyendo

  1. Bifurcar el repositorio

  2. Crear una rama de características ( git checkout -b feature/amazing-feature )

  3. Confirme sus cambios ( git commit -m 'Add amazing feature' )

  4. Empujar a la rama ( git push origin feature/amazing-feature )

  5. Abrir una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Available Tools

7 tools
cpe_lookupA
Read-only

Search for Common Platform Enumeration (CPE) entries by product name in Shodan's CVEDB. Supports pagination and can return either full CPE details or just the total count. Useful for identifying specific versions and configurations of software and hardware.

ParametersJSON Schema
NameRequiredDescriptionDefault
skipNoNumber of CPEs to skip (for pagination).
countNoIf true, returns only the count of matching CPEs.
limitNoMaximum number of CPEs to return (max 1000).
productYesThe name of the product to search for CPEs.

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds pagination support and the option to return only a count. These are behavioral traits beyond what annotations provide, with no contradictions.

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

Conciseness5/5

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

The description is two sentences, front-loaded with the core purpose, followed by key capabilities. Every sentence earns its place with no redundancy.

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?

For a read-only lookup with fully documented parameters and no output schema, the description covers the main behavioral options (pagination, count mode) and a clear use case. It doesn't detail return format, but given the simplicity and annotation coverage, this is adequate.

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?

Schema description coverage is 100%, so all four parameters are documented in the schema. The description mentions pagination and count, but these are already covered in the schema descriptions, so it adds minimal semantic value beyond what is structured.

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 specific verb 'Search' and resource 'CPE entries' within 'Shodan's CVEDB'. It distinguishes from the sibling cves_by_product by focusing on CPEs rather than CVEs, and the name reinforces this.

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

Usage Guidelines4/5

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

The description provides a clear use case: 'identifying specific versions and configurations of software and hardware.' However, it does not explicitly mention alternatives or exclusion criteria. The sibling cves_by_product likely covers CVEs, so the contrast is implied but not stated.

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

cve_lookupA
Read-only

Query detailed vulnerability information from Shodan's CVEDB. Returns comprehensive CVE details including CVSS scores (v2/v3), EPSS probability and ranking, KEV status, proposed mitigations, ransomware associations, and affected products (CPEs).

ParametersJSON Schema
NameRequiredDescriptionDefault
cveYesThe CVE identifier to query (format: CVE-YYYY-NNNNN).

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, covering safety and openness. The description adds substantial behavioral context by listing the specific fields returned (CVSS v2/v3, EPSS, KEV status, mitigations, ransomware associations, CPEs), which goes beyond the annotations and helps the agent set expectations.

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

Conciseness5/5

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

The description is two sentences with zero fluff. The first sentence front-loads the core purpose, and the second enumerates the key return fields. Every clause earns its place.

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?

For a single-parameter lookup tool with no output schema, the description adequately covers the return content by listing the major fields. It does not mention error handling or pagination, but given the simplicity and the openWorldHint annotation, the essential information is present. Minor gaps prevent a 5.

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 fully describes the parameter (pattern and description), so schema coverage is 100%. The description does not add new parameter semantics beyond what the schema already provides; it merely reinforces that a CVE ID is needed. With full schema coverage, baseline 3 is appropriate.

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 states a specific verb ('Query') and resource ('detailed vulnerability information from Shodan's CVEDB'), and enumerates the concrete data returned (CVSS, EPSS, KEV, mitigations, ransomware, CPEs). This clearly distinguishes it from siblings like cves_by_product, which likely searches by product.

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 implies usage when you have a CVE identifier (the required parameter), but it does not explicitly mention when not to use it or recommend alternatives like cves_by_product for product-based queries. Guidance is implicit rather than explicit.

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

cves_by_productA
Read-only

Search for vulnerabilities affecting specific products or CPEs. Supports filtering by KEV status, sorting by EPSS score, date ranges, and pagination. Can search by product name or CPE 2.3 identifier. Returns detailed vulnerability information including severity scores and impact assessments.

ParametersJSON Schema
NameRequiredDescriptionDefault
skipNoNumber of CVEs to skip (for pagination).
countNoIf true, returns only the count of matching CVEs.
cpe23NoThe CPE version 2.3 identifier (format: cpe:2.3:part:vendor:product:version).
limitNoMaximum number of CVEs to return (max 1000).
is_kevNoIf true, returns only CVEs with the KEV flag set.
productNoThe name of the product to search for CVEs.
end_dateNoEnd date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS).
start_dateNoStart date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS).
sort_by_epssNoIf true, sorts CVEs by EPSS score in descending order.

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the tool is known to be a read-only, broad-scope operation. The description adds value by disclosing the return content ('detailed vulnerability information including severity scores and impact assessments') and mentions pagination support, which goes beyond the annotations. It does not contradict any annotation.

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 two sentences, with the primary purpose front-loaded and the supporting capabilities summarized in the second sentence. It is not overly verbose, though the second sentence packs multiple features into one clause. No extraneous information is present, and the structure is logical.

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 the tool's complexity (9 parameters, all with schema descriptions) and the absence of an output schema, the description provides a sufficient overview, including the two search modes (product name vs. CPE identifier) and the return of severity/impact info. It could be more explicit about the relationship between product and cpe23 (e.g., whether they can be combined), but overall it covers the key usage context.

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?

Schema description coverage is 100%, so each parameter is already documented in the schema (e.g., skip, count, cpe23, limit, is_kev, product, dates, sort_by_epss). The description adds only a high-level summary (supports filtering by KEV, sorting by EPSS, date ranges, pagination) without adding new semantic detail. This aligns with the baseline of 3 for fully covered schemas.

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 states a specific verb ('Search') and a precise resource ('vulnerabilities affecting specific products or CPEs'), and lists the supported filtering/sorting capabilities. This clearly distinguishes it from sibling tools like cve_lookup (individual CVE lookup) and cpe_lookup (CPE details), making its purpose unambiguous.

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 clearly conveys that this tool is for product/CPE-based vulnerability searches and mentions the search options (by product name or CPE 2.3). However, it does not explicitly state when to prefer this over sibling tools, such as using cve_lookup for a specific CVE or cpe_lookup for CPE metadata. The guidance is implied rather than explicit, so it earns a 3.

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

dns_lookupA
Read-only

Resolve domain names to IP addresses using Shodan's DNS service. Supports batch resolution of multiple hostnames in a single query. Returns IP addresses mapped to their corresponding hostnames.

ParametersJSON Schema
NameRequiredDescriptionDefault
hostnamesYesList of hostnames to resolve.

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, so the description isn't required to state safety. It adds the batch resolution feature and the mapping behavior, which is useful context. No contradictions.

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

Conciseness5/5

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

Three sentences, no waste, key purpose first.

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

Completeness5/5

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

For a single-parameter read-only tool with no output schema, the description covers purpose, behavior, and return format adequately. No gaps for an agent to call it correctly.

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?

Schema covers the parameter fully (100%). Description adds the 'batch' nuance but essentially repeats the schema's 'list' semantics. Baseline 3 is appropriate.

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?

States a specific verb (Resolve), resource (domain names to IP addresses), and names the service (Shodan's DNS). Implicitly differentiates from reverse_dns_lookup by direction.

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?

Implied usage: if you need to resolve domain names to IPs, this is the tool. But no explicit when-not-to-use or alternatives mentioned. Batch capability is mentioned but not as a selection criterion.

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

ip_lookupA
Read-only

Retrieve comprehensive information about an IP address, including geolocation, open ports, running services, SSL certificates, hostnames, and cloud provider details if available. Returns service banners and HTTP server information when present.

ParametersJSON Schema
NameRequiredDescriptionDefault
ipYesThe IP address to query.

TDQS

A4/5.0
Behavior4/5

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

The description accurately reflects a read-only lookup operation and adds helpful qualifiers like 'if available' and 'when present.' It does not contradict the readOnlyHint annotation, though it omits potential error or rate-limit behavior.

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

Conciseness5/5

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

The description is two sentences, free of fluff, and front-loads the core purpose before listing specific return categories.

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?

With no output schema provided, the description usefully enumerates expected return data. It lacks error/edge-case details, but the listed outputs give sufficient context for typical use.

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 schema already documents the ip parameter as 'The IP address to query,' and the description repeats this without adding format constraints, IPv4/IPv6 guidance, or examples. Schema coverage is effectively complete, so baseline score applies.

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?

Clearly states the tool retrieves comprehensive information about an IP address and enumerates the types of data returned (geolocation, open ports, services, SSL certificates, hostnames, cloud details). This distinguishes it from sibling tools like dns_lookup or cve_lookup.

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 makes the tool's scope clear but does not explicitly state when to use it over alternatives such as shodan_search or dns_lookup. Usage guidance is implied rather than stated.

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

reverse_dns_lookupA
Read-only

Perform reverse DNS lookups to find hostnames associated with IP addresses. Supports batch lookups of multiple IP addresses in a single query. Returns all known hostnames for each IP address, with clear indication when no hostnames are found.

ParametersJSON Schema
NameRequiredDescriptionDefault
ipsYesList of IP addresses to perform reverse DNS lookup on.

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds behavioral context beyond annotations: it supports batch queries, returns all known hostnames per IP, and provides clear indication when none are found. This is useful operational detail that the schema and annotations do not convey.

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

Conciseness5/5

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

Two sentences, no filler. The first sentence states the core purpose, the second adds batch and return details. Information is front-loaded and every word earns its place.

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

Completeness5/5

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

This is a simple one-parameter tool with a clear return description. The description explains what the tool does, how it handles multiple IPs, and what it returns (hostnames and a not-found indication). Annotations cover read-only and open-world aspects. Nothing essential for correct invocation is missing, even without an output schema.

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?

Schema description coverage is 100%, with the ips parameter clearly documented as a list of IP addresses. The description adds no new semantic meaning—'batch lookups' is implied by the array type. Per the baseline rule for high coverage, a 3 is appropriate; the description does not compensate or add value beyond the schema.

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 states a specific action (perform reverse DNS lookups), a clear resource (IP addresses), and the expected output (hostnames). It also distinguishes itself from forward DNS lookups by the term 'reverse,' which is reinforced by the sibling dns_lookup. This is unambiguous and not a tautology.

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 implies usage for IP-to-hostname resolution but does not explicitly contrast with alternatives like dns_lookup or ip_lookup. It mentions batch support, which is a feature, but offers no when-to-use/when-not-to-use guidance. Usage is inferred from the tool name and context rather than stated.

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. 7 tool updatesv1.0.0
    • Changedcpe_lookup2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedcve_lookup2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedcves_by_product2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
    • Changeddns_lookup2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedip_lookup2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedreverse_dns_lookup2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedshodan_search2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
  2. 7 tool updates
    • First observedcpe_lookup
    • First observedcve_lookup
    • First observedcves_by_product
    • First observeddns_lookup
    • First observedip_lookup
    • First observedreverse_dns_lookup
    • First observedshodan_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 7 tools

Disambiguation4/5

Most tools are clearly distinct: ip_lookup, shodan_search, dns_lookup, and reverse_dns_lookup each target a different resource. However, cve_lookup and cves_by_product both return vulnerability information, which could cause some confusion despite their different query approaches.

Naming Consistency4/5

Tool names mostly follow a consistent noun-based pattern (ip_lookup, dns_lookup, cve_lookup, cpe_lookup) with descriptive compound names for searches. The mix of 'lookup' and 'search' verbs is a minor inconsistency, but the pattern is still predictable and readable.

Tool Count5/5

Seven tools is well-scoped for a Shodan-focused server, covering IP intelligence, device search, DNS, and vulnerability data without unnecessary bloat. Each tool serves a distinct purpose within the security research domain.

Completeness4/5

The tool set covers core Shodan functionality: IP lookup, device search, DNS resolution, and CVE/CPE vulnerability research. Minor gaps exist such as account/API info or network/port-specific queries, but the primary workflows for security research are well covered.

Maintenance

ActivityMaintained
ResponsivenessSlow

Resources

Related MCP Connectors

Related MCP Servers

  • Shodan MCP Server

    X3r0K
    F
    license
    Not graded
    quality
    D
    maintenance
    A WebSocket server that provides MCP interface for searching and retrieving information about internet-connected devices, IP addresses, DNS data, and CVE vulnerabilities through the Shodan API.
    3
    -

  • 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
    -

  • Shodan MCP Server

    irootsec
    F
    license
    Not graded
    quality
    D
    maintenance
    Integrates Shodan search capabilities into MCP-compatible applications for discovering internet-connected devices. Enables domain searches, IP lookups, and advanced queries to identify exposed services, infrastructure mapping, and security analysis.
    3
    -

Appeared in Searches