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.
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.
To install Shodan Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @burtthecoder/mcp-shodan --client claudeInstall the server globally via npm:
npm install -g @burtthecoder/mcp-shodanAdd to your Claude Desktop configuration file:
{
"mcpServers": {
"shodan": {
"command": "mcp-shodan",
"env": {
"SHODAN_API_KEY": "your-shodan-api-key"
}
}
}
}Configuration file location:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%Claudeclaude_desktop_config.json
If you prefer to run from source or need to modify the code:
Clone and build:
git clone https://github.com/BurtTheCoder/mcp-shodan.git
cd mcp-shodan
npm install
npm run buildAdd to your Claude Desktop configuration:
{
"mcpServers": {
"shodan": {
"command": "node",
"args": ["/absolute/path/to/mcp-shodan/build/index.js"],
"env": {
"SHODAN_API_KEY": "your-shodan-api-key"
}
}
}
}ip_lookupip (required): IP address to lookupshodan_searchquery (required): Shodan search querymax_results (optional, default: 10): Number of results to returncve_lookupcve (required): CVE identifier in format CVE-YYYY-NNNNN (e.g., CVE-2021-44228)dns_lookuphostnames (required): Array of hostnames to resolvereverse_dns_lookupips (required): Array of IP addresses to lookupcpe_lookupproduct (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 returncves_by_productcpe23 (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)If you see API key related errors (e.g., "Request failed with status code 401"):
Verify the key is correctly set in the SHODAN_API_KEY environment variable
Common Error Codes:
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"
}
}
}
}Testing Your Key:
curl "https://api.shodan.io/dns/resolve?hostnames=google.com&key=your-api-key"If you see module loading errors: 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
To run in development mode with hot reloading:
npm run devThe 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
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.