Shodan MCP Server

Quick Start (Recommended)

Installing via Smithery

Installing Manually

1. Install the server globally via npm:

1. Add to your Claude Desktop configuration file:

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

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

1. Restart Claude Desktop

Alternative Setup (From Source)

1. Clone and build:

1. Add to your Claude Desktop configuration:

Features

• Network Reconnaissance: Query detailed information about IP addresses, including open ports, services, and vulnerabilities

• DNS Operations: Forward and reverse DNS lookups for domains and IP addresses

• Vulnerability Intelligence: Access to Shodan's CVEDB for detailed vulnerability information, CPE lookups, and product-specific CVE tracking

• Device Discovery: Search Shodan's database of internet-connected devices with advanced filtering

Tools

1. IP Lookup Tool

• Name: ip_lookup

• Description: Retrieve comprehensive information about an IP address, including geolocation, open ports, running services, SSL certificates, hostnames, and cloud provider details if available

• Parameters:

• Returns:

2. Shodan Search Tool

• Name: shodan_search

• Description: Search Shodan's database of internet-connected devices

• Parameters:

• Returns:

3. CVE Lookup Tool

• Name: cve_lookup

• Description: Query detailed vulnerability information from Shodan's CVEDB

• Parameters:

• Returns:

4. DNS Lookup Tool

• Name: dns_lookup

• Description: Resolve domain names to IP addresses using Shodan's DNS service

• Parameters:

• Returns:

5. Reverse DNS Lookup Tool

• Name: reverse_dns_lookup

• Description: Perform reverse DNS lookups to find hostnames associated with IP addresses

• Parameters:

• Returns:

6. CPE Lookup Tool

• Name: cpe_lookup

• Description: Search for Common Platform Enumeration (CPE) entries by product name

• Parameters:

• Returns:

7. CVEs by Product Tool

• Name: cves_by_product

• Description: Search for vulnerabilities affecting specific products or CPEs

• Parameters:

• Notes:

• Returns:

Requirements

• Node.js (v18 or later)

• A valid Shodan API Key

Troubleshooting

API Key Issues

1. Verify your API key:

2. Common Error Codes:

3. Configuration Steps: a. Get your API key from Shodan Account b. Add it to your configuration file:c. Save the config file d. Restart Claude Desktop

4. Testing Your Key:

Module Loading Issues

1. For global installation: Use the simple configuration shown in Quick Start

2. For source installation: Ensure you're using Node.js v18 or later

Development

Error Handling

• Invalid API keys

• Rate limiting

• Network errors

• Invalid input parameters

• Invalid CVE formats

• Invalid CPE lookup parameters

• Invalid date formats

• Mutually exclusive parameter validation

Version History

• v1.0.12: Added reverse DNS lookup and improved output formatting

• v1.0.7: Added CVEs by Product search functionality and renamed vulnerabilities tool to cve_lookup

• v1.0.6: Added CVEDB integration for enhanced CVE lookups and CPE search functionality

• v1.0.0: Initial release with core functionality

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

Shodan MCP Server

Quick Start (Recommended)

Installing via Smithery

Installing Manually

1. Install the server globally via npm:

1. Add to your Claude Desktop configuration file:

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

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

1. Restart Claude Desktop

Alternative Setup (From Source)

1. Clone and build:

1. Add to your Claude Desktop configuration:

Features

• Network Reconnaissance: Query detailed information about IP addresses, including open ports, services, and vulnerabilities

• DNS Operations: Forward and reverse DNS lookups for domains and IP addresses

• Vulnerability Intelligence: Access to Shodan's CVEDB for detailed vulnerability information, CPE lookups, and product-specific CVE tracking

• Device Discovery: Search Shodan's database of internet-connected devices with advanced filtering

Tools

1. IP Lookup Tool

• Name: ip_lookup

• Description: Retrieve comprehensive information about an IP address, including geolocation, open ports, running services, SSL certificates, hostnames, and cloud provider details if available

• Parameters:

• Returns:

2. Shodan Search Tool

• Name: shodan_search

• Description: Search Shodan's database of internet-connected devices

• Parameters:

• Returns:

3. CVE Lookup Tool

• Name: cve_lookup

• Description: Query detailed vulnerability information from Shodan's CVEDB

• Parameters:

• Returns:

4. DNS Lookup Tool

• Name: dns_lookup

• Description: Resolve domain names to IP addresses using Shodan's DNS service

• Parameters:

• Returns:

5. Reverse DNS Lookup Tool

• Name: reverse_dns_lookup

• Description: Perform reverse DNS lookups to find hostnames associated with IP addresses

• Parameters:

• Returns:

6. CPE Lookup Tool

• Name: cpe_lookup

• Description: Search for Common Platform Enumeration (CPE) entries by product name

• Parameters:

• Returns:

7. CVEs by Product Tool

• Name: cves_by_product

• Description: Search for vulnerabilities affecting specific products or CPEs

• Parameters:

• Notes:

• Returns:

Requirements

• Node.js (v18 or later)

• A valid Shodan API Key

Troubleshooting

API Key Issues

1. Verify your API key:

2. Common Error Codes:

3. Configuration Steps: a. Get your API key from Shodan Account b. Add it to your configuration file:c. Save the config file d. Restart Claude Desktop

4. Testing Your Key:

Module Loading Issues

1. For global installation: Use the simple configuration shown in Quick Start

2. For source installation: Ensure you're using Node.js v18 or later

Development

Error Handling

• Invalid API keys

• Rate limiting

• Network errors

• Invalid input parameters

• Invalid CVE formats

• Invalid CPE lookup parameters

• Invalid date formats

• Mutually exclusive parameter validation

Version History

• v1.0.12: Added reverse DNS lookup and improved output formatting

• v1.0.7: Added CVEs by Product search functionality and renamed vulnerabilities tool to cve_lookup

• v1.0.6: Added CVEDB integration for enhanced CVE lookups and CPE search functionality

• v1.0.0: Initial release with core functionality

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License