Hexix23/shodan-mcp

## 🔍 Overview
SHODAN-MCP is a powerful interface to the Shodan API, designed to simplify interaction with the world's first search engine for Internet-connected devices. It provides a comprehensive set of tools for security researchers, penetration testers, and cybersecurity professionals to explore, analyze, and monitor the global internet landscape.
> "The more systems you can access, the more power you have."
## ✨ Key Features
### 🔎 Search & Discovery
Advanced Search: Query the Shodan database using powerful filtering capabilities and multiple parameters
Result Analysis: Detailed breakdowns of search results with geographic distribution and organization insights
Count Function: Get total numbers and statistical breakdowns without consuming API credits
### 📡 Host Intelligence
Detailed Host Information: Comprehensive data about any IP address including all services, banners and configurations
Port Scanning: View all open ports and running services on target systems
Banner Grabbing: Access complete service banners and headers for in-depth analysis
### 🔒 Security Research
Vulnerability Discovery: Find devices affected by specific CVEs or with particular vulnerabilities
CVE Information: Get detailed intelligence on Common Vulnerabilities and Exposures
Exploitation Risk Assessment: Evaluate threats with CVSS scores and EPSS exploitation likelihood metrics
### 🌍 Network Mapping
DNS Intelligence: Retrieve comprehensive DNS information and subdomain discovery
Domain Insights: Analyze domain infrastructure and associated services
Reverse DNS: Map IP addresses to hostnames for network enumeration
## 🛠️ Installation & Setup
### Prerequisites
Python 3.8 or higher
Shodan API key (Get one here)
pip or uv for dependency management
### Basic Installation
bash
# Clone the repository
git clone https://github.com/yourusername/shodan-mcp.git
cd shodan-mcp
# Install dependencies
pip install -r requirements.txt
# Set up your Shodan API key
echo "SHODANAPIKEY=yourapikeyhere" > shodan-mcp-server/.env
### Integration Options
SHODAN-MCP can be integrated with various AI and development environments:
#### 🤖 Claude Integration
Claude can interact with SHODAN-MCP using the MCP protocol:
1. In Claude Desktop, go to Settings → Developer → Edit Config
2. Edit the claudedesktopconfig.json file and add the following configuration:
json
"mcpServers": {
"shodan": {
"command": "/path/to/uv",
"args": [
"--directory",
"/path/to/shodan-mcp/shodan-mcp-server",
"run",
"shodanmcp.py"
3. Replace /path/to/uv with your actual path to the uv executable (e.g., ~/.local/bin/uv on macOS/Linux)
4. Replace /path/to/shodan-mcp with the actual path to your shodan-mcp project directory
5. Save the configuration and restart Claude
6. Now you can ask Claude to use Shodan tools directly in your conversations
#### 🖥️ Cursor IDE Integration
Cursor seamlessly integrates with SHODAN-MCP through the MCP configuration file:
1. The MCP configuration file is located at ~/.cursor/mcp.json (macOS/Linux)
2. Add the following configuration to your mcp.json:
json
"mcpServers": {
"shodan": {
"command": "/path/to/uv",
"args": [
"--directory",
"/path/to/shodan-mcp/shodan-mcp-server",
"run",
"shodanmcp.py"