Shodan MCP Server (stdio)
Model Context Protocol (MCP) server integration for Shodan API, enabling Claude AI to perform comprehensive security reconnaissance, vulnerability assessment, and threat intelligence gathering.
Features
- Comprehensive Host Search: Search Shodan's database of internet-connected devices
- Detailed Host Information: Get in-depth data about specific IP addresses
- DNS Operations: Forward and reverse DNS lookups
- Vulnerability Discovery: Find hosts with specific CVEs and security issues
- Exploit Database: Search for available exploits
- API Management: Monitor query credits and usage
- Protocol/Port Information: Access Shodan's supported protocols and ports
Prerequisites
- Node.js 18.0.0 or higher
- Shodan API key (Get one here)
- Claude Desktop or compatible MCP client
Installation
1. Clone and Install Dependencies
cd /path/to/shodan-mcp-server
npm install
2. Get Shodan API Key
3. Configure Environment
Create a .env file:
echo "SHODAN_API_KEY=your_api_key_here" > .env
4. Configure Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"shodan": {
"command": "node",
"args": ["/path/to/shodan-mcp-server/src/index.js"],
"env": {
"SHODAN_API_KEY": "your_api_key_here"
}
}
}
}
Available Tools
shodan_host_search
Search Shodan for hosts matching a query.
Parameters:
query(required): Shodan search queryfacets(optional): Comma-separated facets for aggregationpage(optional): Page number for pagination
Example:
Query: "apache country:US"
Facets: "country,org,port"
shodan_host_info
Get detailed information about a specific IP address.
Parameters:
ip(required): IP address to lookuphistory(optional): Include historical data
Example:
IP: "8.8.8.8"
History: true
shodan_dns_lookup
Resolve domain names to IP addresses.
Parameters:
hostnames(required): Array of hostnames
Example:
Hostnames: ["example.com", "google.com"]
shodan_dns_reverse
Perform reverse DNS lookup on IP addresses.
Parameters:
ips(required): Array of IP addresses
Example:
IPs: ["8.8.8.8", "1.1.1.1"]
shodan_api_info
Get information about your API plan and remaining credits.
Parameters: None
shodan_exploits_search
Search the Shodan Exploits database.
Parameters:
query(required): Search queryfacets(optional): Facets for aggregationpage(optional): Page number
Example:
Query: "CVE-2021-44228"
Facets: "type,platform"
shodan_ports
Get list of ports that Shodan crawls.
Parameters: None
shodan_protocols
Get supported protocols for querying.
Parameters: None
shodan_count
Get total count of results for a query without returning data.
Parameters:
query(required): Shodan search queryfacets(optional): Facets for aggregated counts
shodan_query_search
Search for saved community queries.
Parameters:
query(required): Search termpage(optional): Page number
shodan_query_tags
Get popular tags for saved queries.
Parameters:
size(optional): Number of tags to return (default: 10)
Shodan Query Syntax
Basic Filters
city:"San Francisco" - Filter by city
country:US - Filter by country code
org:"Google" - Filter by organization
net:192.168.0.0/24 - Filter by IP range
port:22 - Filter by port
product:Apache - Filter by product name
version:2.4.1 - Filter by version
os:"Windows 10" - Filter by operating system
Vulnerability Filters
vuln:CVE-2021-44228 - Search for specific CVE
vuln:CVE-2020-* - Search for CVEs from 2020
HTTP Filters
http.title:"Admin Panel" - Filter by page title
http.html:"password" - Search in HTML content
http.status:200 - Filter by HTTP status
http.component:"wordpress" - Filter by web component
SSL Filters
ssl:"example.com" - Search by SSL certificate
ssl.cert.expired:true - Find expired certificates
ssl.version:sslv2 - Filter by SSL version
ssl.cipher:export - Find weak ciphers
Combining Filters
port:22 country:US org:"Amazon"
apache city:"Los Angeles" vuln:CVE-2021-44228
Usage Examples
1. Asset Discovery
// Find all assets for an organization
{
"query": "org:\"Example Corp\"",
"facets": "country,port,product"
}
2. Vulnerability Assessment
// Find systems vulnerable to Log4Shell
{
"query": "vuln:CVE-2021-44228 country:US",
"page": 1
}
3. Threat Intelligence
// Find potential C2 infrastructure
{
"query": "product:\"Cobalt Strike\"",
"facets": "country,org"
}
4. DNS Investigation
// Resolve multiple domains
{
"hostnames": [
"example.com",
"suspicious-domain.com"
]
}
5. Exploit Research
// Find exploits for a CVE
{
"query": "CVE-2021-44228",
"facets": "type,platform,author"
}
Skills
Three comprehensive skills are included:
1. shodan-recon
Perform reconnaissance and asset discovery. Automates the process of:
- DNS enumeration
- Asset discovery
- Port and service enumeration
- Detailed host analysis
- Comprehensive reporting
2. shodan-vuln-scan
Identify and assess vulnerabilities. Includes:
- CVE discovery
- Exploit availability checking
- Risk assessment
- Remediation recommendations
- Vulnerability matrix generation
3. shodan-threat-intel
Gather threat intelligence. Capabilities:
- C2 infrastructure tracking
- Phishing infrastructure identification
- Malware distribution point discovery
- IOC enrichment
- Threat actor tracking
- Temporal analysis
Development
Running in Development
npm run dev
Testing Tools
# Test the server manually
node src/index.js
# In another terminal, send test requests
# (requires MCP client for full testing)
Adding New Tools
- Add tool definition to
TOOLSarray insrc/index.js - Add case handler in
CallToolRequestSchemahandler - Update README with new tool documentation