The mcp-shodan server enables querying and analysis of Shodan's network intelligence and security services:
Perform IP reconnaissance to retrieve geolocation, open ports, services, SSL certificates, hostnames, and cloud provider details
Search Shodan's database for internet-connected devices with advanced filters and result limiting
Query detailed vulnerability information from Shodan's CVEDB including CVSS scores and EPSS rankings
Resolve domain names to IP addresses (supports batch queries)
Perform reverse DNS lookups to find hostnames associated with IP addresses (supports batch queries)
Search for Common Platform Enumeration (CPE) entries by product name with pagination options
Find vulnerabilities affecting specific products or CPEs with filtering by KEV status, sorting by EPSS, date ranges, and pagination
Requires Node.js v18 or later as a runtime environment for the MCP server.
Shodan MCP Server
A Model Context Protocol (MCP) server for querying the Shodan API and Shodan CVEDB. This server provides comprehensive access to Shodan's network intelligence and security services, including IP reconnaissance, DNS operations, vulnerability tracking, and device discovery. All tools provide structured, formatted output for easy analysis and integration.
Quick Start (Recommended)
Installing via Smithery
To install Shodan Server for Claude Desktop automatically via Smithery:
Installing Manually
Install the server globally via npm:
Add to your Claude Desktop configuration file:
Configuration file location:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Restart Claude Desktop
Alternative Setup (From Source)
If you prefer to run from source or need to modify the code:
Clone and build:
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:
ip
(required): IP address to lookup
Returns:
IP Information (address, organization, ISP, ASN)
Location (country, city, coordinates)
Services (ports, protocols, banners)
Cloud Provider details (if available)
Associated hostnames and domains
Tags
2. Shodan Search Tool
Name:
shodan_search
Description: Search Shodan's database of internet-connected devices
Parameters:
query
(required): Shodan search querymax_results
(optional, default: 10): Number of results to return
Returns:
Search summary with total results
Country-based distribution statistics
Detailed device information including:
Basic information (IP, organization, ISP)
Location data
Service details
Web server information
Associated hostnames and domains
3. CVE Lookup Tool
Name:
cve_lookup
Description: Query detailed vulnerability information from Shodan's CVEDB
Parameters:
cve
(required): CVE identifier in format CVE-YYYY-NNNNN (e.g., CVE-2021-44228)
Returns:
Basic Information (ID, published date, summary)
Severity Scores:
CVSS v2 and v3 with severity levels
EPSS probability and ranking
Impact Assessment:
KEV status
Proposed mitigations
Ransomware associations
Affected products (CPEs)
References
4. DNS Lookup Tool
Name:
dns_lookup
Description: Resolve domain names to IP addresses using Shodan's DNS service
Parameters:
hostnames
(required): Array of hostnames to resolve
Returns:
DNS resolutions mapping hostnames to IPs
Summary of total lookups and queried hostnames
5. Reverse DNS Lookup Tool
Name:
reverse_dns_lookup
Description: Perform reverse DNS lookups to find hostnames associated with IP addresses
Parameters:
ips
(required): Array of IP addresses to lookup
Returns:
Reverse DNS resolutions mapping IPs to hostnames
Summary of total lookups and results
6. CPE Lookup Tool
Name:
cpe_lookup
Description: Search for Common Platform Enumeration (CPE) entries by product name
Parameters:
product
(required): Name of the product to search forcount
(optional, default: false): If true, returns only the count of matching CPEsskip
(optional, default: 0): Number of CPEs to skip (for pagination)limit
(optional, default: 1000): Maximum number of CPEs to return
Returns:
When count is true: Total number of matching CPEs
When count is false: List of CPEs with pagination details
7. CVEs by Product Tool
Name:
cves_by_product
Description: Search for vulnerabilities affecting specific products or CPEs
Parameters:
cpe23
(optional): CPE 2.3 identifier (format: cpe:2.3:part:vendor:product:version)product
(optional): Name of the product to search for CVEscount
(optional, default: false): If true, returns only the count of matching CVEsis_kev
(optional, default: false): If true, returns only CVEs with KEV flag setsort_by_epss
(optional, default: false): If true, sorts CVEs by EPSS scoreskip
(optional, default: 0): Number of CVEs to skip (for pagination)limit
(optional, default: 1000): Maximum number of CVEs to returnstart_date
(optional): Start date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS)end_date
(optional): End date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS)
Notes:
Must provide either cpe23 or product, but not both
Date filtering uses published time of CVEs
Returns:
Query information
Results summary with pagination details
Detailed vulnerability information including:
Basic information
Severity scores
Impact assessments
References
Requirements
Node.js (v18 or later)
A valid Shodan API Key
Troubleshooting
API Key Issues
If you see API key related errors (e.g., "Request failed with status code 401"):
Verify your API key:
Must be a valid Shodan API key from your account settings
Ensure the key has sufficient credits/permissions for the operation
Check for extra spaces or quotes around the key in the configuration
Verify the key is correctly set in the SHODAN_API_KEY environment variable
Common Error Codes:
401 Unauthorized: Invalid API key or missing authentication
402 Payment Required: Out of query credits
429 Too Many Requests: Rate limit exceeded
Configuration Steps: a. Get your API key from Shodan Account b. Add it to your configuration file:
{ "mcpServers": { "shodan": { "command": "mcp-shodan", "env": { "SHODAN_API_KEY": "your-actual-api-key-here" } } } }c. Save the config file d. Restart Claude Desktop
Testing Your Key:
Try a simple query first (e.g., dns_lookup for "google.com")
Check your Shodan account dashboard for credit status
Verify the key works directly with curl:
curl "https://api.shodan.io/dns/resolve?hostnames=google.com&key=your-api-key"
Module Loading Issues
If you see module loading errors:
For global installation: Use the simple configuration shown in Quick Start
For source installation: Ensure you're using Node.js v18 or later
Development
To run in development mode with hot reloading:
Error Handling
The server includes comprehensive error handling for:
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
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
local-only server
The server can only run on the client's local machine because it depends on local resources.
MCP server for querying the Shodan API and Shodan CVEDB. This server provides tools for IP lookups, device searches, DNS lookups, vulnerability queries, CPE lookups, and more.
Related MCP Servers
- AsecurityAlicenseAqualityThe Search MCP Server enables seamless integration of network and local search capabilities in tools like Claude Desktop and Cursor, utilizing the Brave Search API for high-concurrency and asynchronous requests.Last updated -173MIT License
- AsecurityAlicenseAqualityA Model Context Protocol (MCP) server for querying the CVE-Search API. This server provides comprehensive access to CVE-Search, browse vendor and product、get CVE per CVE-ID、get the last updated CVEs.Last updated -653MIT License
- -securityFlicense-qualityA 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.Last updated -2
- -securityFlicense-qualityThis 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.Last updated -1
Appeared in Searches
- Information on LinkedIn Business or LinkedIn Advertising
- Information about the VIX (Volatility Index)
- Accessing Clearbit APIs for Company Information and Website Visitor Data
- A guide to finding data in public databases
- How to retrieve information about a device using Microsoft Defender, Intune, and Jamf