Shodan MCP Conduit

This Model Context Protocol (MCP) module establishes connectivity to the Shodan threat intelligence platform (https://shodan.io) and its associated Common Vulnerabilities and Exposures Database (CVEDB) (https://cvedb.shodan.io). It grants users access to granular network intelligence, encompassing IP footprinting, domain-to-IP resolution services, tracking of known security flaws, and broad discovery of internet-facing assets. All executed queries yield canonical, machine-readable data structures for seamless integration into automated workflows.

Expedited Deployment

Installation via Smithery (Recommended)

Automate the deployment of the Shodan Server module directly into your Claude Desktop environment using the Smithery CLI:

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

Manual NPM Installation

1. Install the utility globally using npm: bash npm install -g @burtthecoder/mcp-shodan

2. Integrate the server definition into your Claude Desktop configuration file:

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

Configuration path specifics: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Apply changes by restarting the Claude Desktop application.

Source Code Deployment

For users intending to compile from source or modify the underlying logic:

1. Clone and build the repository: bash git clone https://github.com/BurtTheCoder/mcp-shodan.git cd mcp-shodan npm install npm run build

2. Update your Claude Desktop configuration to invoke the compiled JavaScript:

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

Core Capabilities

• Network Probing: Execute deep queries on specified IP ranges, revealing active services, listening ports, and associated security exposures.
• Domain Resolution: Provide forward (domain to IP) and reverse (IP to hostname) lookups leveraging Shodan's global DNS infrastructure.
• Threat Intelligence: Direct access to CVEDB data for precise vulnerability assessment, including Common Platform Enumeration (CPE) mapping and CVE tracking.
• Asset Mapping: Search Shodan's massive repository of observed internet-connected devices, filterable by numerous criteria.

Available Functions

1. IP Inspection Tool

• Identifier: ip_details_gather
• Purpose: Fetch a holistic profile for a given IP address, detailing its geographic location, network service mappings, SSL/TLS metadata, associated hostnames, and cloud hosting affiliation.
• Arguments:
• target_ip (mandatory): The IPv4 or IPv6 address being investigated.
• Output Schema:
• Network Identity (Address, Owner Organization, ISP, Autonomous System Number)
• Geospatial Data (Country, Municipality, Latitude/Longitude)
• Operational Services (Port numbers, transport protocols, captured service banners)
• Cloud Metadata (If identifiable)
• Registered Hostnames
• Classification Tags

2. Shodan Database Search Tool

• Identifier: asset_discovery_query
• Purpose: Formulate custom search strings against the entire indexed Shodan device dataset.
• Arguments:
• search_criteria (mandatory): The complex Shodan Query Language string.
• result_cap (optional, default: 10): Maximum number of resultant device records to return.
• Output Schema:
• Search summary including the total population matching the criteria.
• Aggregated statistics based on country origin.
• Detailed records for each discovered asset, including IP, AS info, location, and specific service fingerprinting.

3. CVE Intelligence Retrieval Tool

• Identifier: vulnerability_data_fetch
• Purpose: Obtain deep analysis for a specific Common Vulnerabilities and Exposures identifier.
• Arguments:
• cve_id (mandatory): The standardized CVE designation (e.g., CVE-2023-99999).
• Output Schema:
• Core Metadata (ID, initial disclosure date, descriptive summary)
• Risk Quantification:
  • CVSS scores (v2/v3) and qualitative severity labels.
  • Exploit Prediction Scoring System (EPSS) score and percentile rank.
• Exposure Metrics:
  • Known Exploited Vulnerabilities (KEV) status.
  • Vendor-suggested remediation steps.
  • Linkages to known ransomware campaigns.
• Affected Software Signatures (CPE list).
• External Information References.

4. Forward DNS Resolution Tool

• Identifier: forward_dns_resolve
• Purpose: Leverage Shodan's infrastructure to resolve multiple domain names into their corresponding IP addresses.
• Arguments:
• domain_list (mandatory): An array containing the hostnames requiring IP translation.
• Output Schema:
• Mapping table correlating each input hostname with its resolved IP(s).
• Tally of successful resolutions versus total inputs.

5. Reverse IP-to-Hostname Tool

• Identifier: reverse_hostname_map
• Purpose: Identify domain names associated with a provided set of IP addresses.
• Arguments:
• ip_addresses (mandatory): An array of IP addresses for reverse lookup.
• Output Schema:
• Reverse mapping structure linking each IP to its associated hostnames.
• Summary statistics on the lookups performed.

6. Product CPE Search Tool

• Identifier: cpe_inventory_lookup
• Purpose: Search the database for Common Platform Enumeration entries based on product names.
• Arguments:
• product_name_pattern (mandatory): Textual pattern to match against product names.
• return_count_only (optional, default: false): Boolean flag to return only the total match quantity.
• offset (optional, default: 0): Pagination skip index.
• page_size (optional, default: 1000): Maximum records per result set.
• Output Schema:
• If return_count_only is true: The total count of matching CPE records.
• Otherwise: A paginated list of full CPE definitions.

7. Product-Specific CVE Tool

• Identifier: cves_by_associated_product
• Purpose: Retrieve vulnerabilities linked specifically to a known product or CPE string.
• Arguments:
• cpe_identifier (optional): Formal CPE 2.3 string for precise targeting.
• product_name_query (optional): Text search for products.
• tally_only (optional, default: false): Return only the total count of associated CVEs.
• only_known_exploited (optional, default: false): Filter results to only include KEV-flagged vulnerabilities.
• prioritize_epss (optional, default: false): Order results by descending EPSS probability score.
• page_offset (optional, default: 0): Pagination start index.
• page_limit (optional, default: 1000): Maximum CVEs returned per call.
• start_time (optional): Timestamp (ISO 8601) to begin filtering by CVE publication date.
• end_time (optional): Timestamp (ISO 8601) to end filtering by CVE publication date.
• Constraints:
• A search must specify either cpe_identifier or product_name_query.
• Output Schema:
• Metadata detailing the query parameters used.
• Summary object indicating result counts and pagination status.
• An array containing detailed vulnerability records (including risk scores and references).

Prerequisites

• Runtime Environment: Node.js installation, version 18 or higher is mandated.
• Authentication Token: A valid, active Shodan API Key is necessary for all communication.

Troubleshooting Connection Issues

Authentication Failures (HTTP 401 Errors)

If you encounter errors indicating authorization problems:

1. Key Validation: Confirm the API key sourced from your Shodan console is accurate.
2. Credit Check: Ensure your account has sufficient remaining query credits for the requested operation.
3. Format Integrity: Eliminate extraneous whitespace or quotation marks surrounding the key in the configuration file.

4. Environment Variable Check: Confirm SHODAN_API_KEY is correctly populated.

5. HTTP Status Codes:

6. 401: Authentication failure (Key invalid or missing).
7. 402: Rate limit or credit exhaustion.

8. 429: Service rate threshold temporarily exceeded.

9. Configuration Procedure Recap: a. Acquire key from Shodan Portal. b. Update your configuration:

   { "mcpServers": { "shodan_net_intel": { "command": "mcp-shodan", "env": { "SHODAN_API_KEY": "INSERT_YOUR_REAL_KEY_HERE" } } } }

c. Save and relaunch Claude Desktop.

1. External Verification: Test functionality outside of Claude using curl: bash curl "https://api.shodan.io/dns/info?hostnames=example.com&key=YOUR_API_KEY"

Module Loading Errors

If runtime errors related to module startup occur: 1. Global Install: Ensure you are using the simple configuration if installed globally. 2. Source Install: Verify that the environment is running Node.js v18 or a newer iteration.

Development Workflow

To activate live reloading and development mode: bash npm run dev

Robust Exception Handling

The server layer is engineered with comprehensive defensive coding to gracefully manage: - Invalid API token usage. - API provider rate limiting enforcement. - General network communication failures. - Input validation failures for all function arguments. - Malformed CVE and CPE identifiers. - Inconsistent date format submissions. - Conflicts arising from using mutually exclusive input parameters.

Revision Log

• v1.0.12: Introduced capability for reverse DNS resolution and refined data serialization procedures.
• v1.0.7: Integrated the 'Search CVEs by Product' utility; renamed the former general vulnerability tool to vulnerability_data_fetch.
• v1.0.6: Incorporated full CVEDB data access and implemented the CPE search function.
• v1.0.0: Initial deployment containing foundational internet scanning and data retrieval features.

Collaboration Guidelines

1. Create a fork of this repository.
2. Establish a dedicated feature branch (git checkout -b feature/superb-enhancement).
3. Commit your modifications (git commit -m 'Implement superb enhancement logic').
4. Push the branch to your remote fork (git push origin feature/superb-enhancement).
5. Submit a Pull Request for review.

Governing License

This software is distributed under the terms of the MIT License. Consult the LICENSE file for comprehensive details.

---

Note on XMLHttpRequest (XHR): XHR is a foundational JavaScript API object facilitating asynchronous HTTP communication between a web browser and a remote server post-initial page load. It is the backbone of Asynchronous JavaScript and XML (Ajax) programming. Before XHR, server interaction relied almost entirely on full page reloads triggered by form submissions or link navigation.

== Historical Context == The core concept for this asynchronous communication pattern originated in 2000 via Microsoft Outlook development. It was first implemented in Internet Explorer 5 (1999), though it initially utilized proprietary ActiveXObject identifiers rather than the standardized XMLHttpRequest string. By the release of Internet Explorer 7 (2006), universal browser support for the standardized identifier was achieved, encompassing Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Path === The W3C issued a formal Working Draft specification for the XMLHttpRequest object in April 2006. A subsequent Level 2 draft in February 2008 augmented capabilities, notably enabling cross-origin requests, progress monitoring, and raw byte stream handling. By late 2011, Level 2 features were merged into the primary specification. Since 2012, the WHATWG has assumed maintenance, developing a living standard documented using Web IDL.

== Operational Steps == Constructing a typical network request via XMLHttpRequest involves a sequential process:

1. Instantiate the XMLHttpRequest object using its constructor.
2. Invoke the .open() method to define the request method (GET/POST), the target URI, and whether the operation should be synchronous or asynchronous.
3. Crucially, for asynchronous operations, register an event handler callback to process state transitions.
4. Begin the transmission sequence by calling the .send() method, optionally supplying request body data.
5. Process the response within the listener. Upon reaching state 4 ("done"), the response payload is typically available in the .responseText property.

Beyond these fundamentals, XHR offers granular control: custom headers can be injected, data uploads can be managed precisely, responses can be automatically parsed from JSON into native JavaScript objects, and operations can be prematurely terminated or time-limited.