Shodan MCP

What is SHODAN-MCP?

SHODAN-MCP is a Python-based tool that acts as a powerful interface to the Shodan API. It simplifies interactions with Shodan, which is essentially a search engine for Internet-connected devices. The project aims to provide a comprehensive set of tools for cybersecurity professionals to explore, analyze, and monitor the global internet landscape.

How to use SHODAN-MCP?

To use SHODAN-MCP, you need Python 3.8 or higher and a Shodan API key. The basic installation involves cloning the repository, installing dependencies using pip or uv, and setting up your Shodan API key in a .env file.

SHODAN-MCP is designed for integration with AI assistants and IDEs that support the MCP protocol, such as Claude, Cursor IDE, and VSCode. Configuration involves adding specific JSON snippets to the respective application's settings, pointing to the shodan-mcp-server directory and the shodan_mcp.py script. Once configured, you can interact with Shodan using natural language queries within these environments.

Key Features of SHODAN-MCP

Search & Discovery

Advanced Search: Query the Shodan database with powerful filtering.
Result Analysis: Detailed breakdowns of search results, including geographic distribution.
Count Function: Get total numbers and statistical breakdowns without consuming API credits.

Host Intelligence

Detailed Host Information: Comprehensive data about any IP address, services, and configurations.
Port Scanning: View open ports and running services.
Banner Grabbing: Access complete service banners and headers.

Security Research

Vulnerability Discovery: Find devices affected by specific CVEs.
CVE Information: Get detailed intelligence on Common Vulnerabilities and Exposures.
Exploitation Risk Assessment: Evaluate threats with CVSS scores and EPSS metrics.

Network Mapping

DNS Intelligence: Retrieve comprehensive DNS information and subdomain discovery.
Domain Insights: Analyze domain infrastructure.
Reverse DNS: Map IP addresses to hostnames.

Use Cases of SHODAN-MCP

SHODAN-MCP is primarily used by security researchers, penetration testers, and cybersecurity professionals for:

Vulnerability Assessment: Identifying devices with known vulnerabilities.
Threat Intelligence: Gaining insights into the global internet landscape.
Network Enumeration: Mapping network infrastructure and identifying open services.
Security Auditing: Checking for misconfigurations and exposed services.
Integration with AI Assistants: Leveraging natural language processing for Shodan queries.

FAQ about SHODAN-MCP

Q: What are the prerequisites for using SHODAN-MCP? A: You need Python 3.8 or higher, a Shodan API key, and pip or uv for dependency management.

Q: How do I get a Shodan API key? A: You can obtain a Shodan API key by signing up at https://account.shodan.io/.

Q: Is SHODAN-MCP compatible with Windows? A: While not fully tested, it should work in theory. The project has been primarily developed and tested on macOS and Linux environments.

Q: How does SHODAN-MCP handle API key security? A: It uses a .env file to store your Shodan API key, which is included in .gitignore to prevent it from being uploaded to public repositories. You should never share your API key.

Q: Does using SHODAN-MCP consume Shodan API credits? A: Some commands do consume Shodan API credits. The count command, however, does not.

Q: What are the planned future features for SHODAN-MCP? A: Upcoming features include Markdown report generation, batch processing, advanced visualization, a Docker container, and expanded cross-platform testing.

🌐 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

# 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 "SHODAN_API_KEY=your_api_key_here" > 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:

In Claude Desktop, go to Settings → Developer → Edit Config

Edit the claude_desktop_config.json file and add the following configuration:

"mcpServers": {
  "shodan": {
    "command": "/path/to/uv",
    "args": [
      "--directory",
      "/path/to/shodan-mcp/shodan-mcp-server",
      "run",
      "shodan_mcp.py"
    ]
  }
}

Replace /path/to/uv with your actual path to the uv executable (e.g., ~/.local/bin/uv on macOS/Linux)
Replace /path/to/shodan-mcp with the actual path to your shodan-mcp project directory
Save the configuration and restart Claude
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:

The MCP configuration file is located at ~/.cursor/mcp.json (macOS/Linux)

Add the following configuration to your mcp.json:

{
  "mcpServers": {
    "shodan": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/shodan-mcp/shodan-mcp-server",
        "run",
        "shodan_mcp.py"
      ],
      "env": {}
    }
  }
}

Replace /path/to/uv with your actual path to the uv executable (e.g., ~/.local/bin/uv on macOS/Linux)
Replace /path/to/shodan-mcp with the actual path to your shodan-mcp project directory
Save the configuration and restart Cursor
The Shodan MCP tools will now be available in your Cursor environment

📝 VSCode Integration

For VSCode users, add the following to your settings.json file:

Open VS Code settings (⌘+Shift+P, then type "Preferences: Open Settings (JSON)")

Add the following configuration:

"mcp": {
  "inputs": [],
  "servers": {
    "shodan": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/shodan-mcp/shodan-mcp-server",
        "run",
        "shodan_mcp.py"
      ],
      "env": {}
    }
  }
}

Replace /path/to/uv with your actual path to the uv executable (e.g., ~/.local/bin/uv on macOS/Linux or the full path on Windows)
Replace /path/to/shodan-mcp with the actual path to your shodan-mcp project directory
Save the settings and restart VS Code
Access through the built-in AI features or command palette

Installation with UV

**uv is recommended for managing Python environments and dependencies due to its speed and reliability:

# Install uv if you don't have it
curl -sSf https://github.com/astral-sh/uv/releases/download/0.1.21/uv-installer.sh | sh

# Install project dependencies with uv
uv pip install -r requirements.txt

# Run the MCP server with uv
uv --directory /path/to/shodan-mcp/shodan-mcp-server run shodan_mcp.py

🚀 Available Commands

Category	Command	Description
Core	`test`	Test if the MCP server is working correctly
Core	`check_key`	Verify Shodan API key validity and view account information
Search	`search`	Search the Shodan database with powerful filtering capabilities
Search	`count`	Count results for a query without consuming API credits
Search	`get_filters`	Get all available Shodan search filters
Search	`get_facets`	Get available facets for statistical analysis
Host	`host`	Get detailed information about a specific IP address
DNS	`domain_info`	Get DNS information and subdomains for a domain
DNS	`dns_lookup`	Resolve hostnames to IP addresses
DNS	`reverse_dns`	Find hostnames associated with IP addresses
Vulnerabilities	`cve_info`	Get detailed information about a specific CVE
Vulnerabilities	`find_cpes`	Find CPE identifiers for a specific product
Vulnerabilities	`find_cves`	Find vulnerabilities by product or CPE identifier

📊 Example Usage

Integration with AI Assistants

SHODAN-MCP is designed to be used through AI assistants and IDEs that support the MCP protocol. You can interact with Shodan using natural language:

"Find all exposed Jenkins servers in Germany"
"Check if 8.8.8.8 has any known vulnerabilities"
"Show me the distribution of Nginx servers by country"
"List the top 5 countries with vulnerable MongoDB instances"
"Get DNS information for example.com"

Available Commands through MCP

Once configured in your IDE or AI assistant, SHODAN-MCP offers the following commands:

💻 System Compatibility

Platform	Supported	Notes
macOS	✅	Tested on Intel & Apple Silicon (M1/M2/M3)
Linux	✅	Tested on Ubuntu 22.04
Windows	⚠️	Not fully tested, but should work in theory
Docker	⚠️	Support planned but not yet implemented
Cloud	⚠️	Support planned but not yet tested

Note: This project has been primarily developed and tested on macOS and Linux environments. Contributions to expand and test compatibility on other platforms are welcome!

🔧 Technical Architecture

SHODAN-MCP is built using:

FastMCP: High-performance async framework for API interactions
Shodan API Client: Official Python client for Shodan
HTTPX: Modern asynchronous HTTP client
Python-dotenv: For secure environment variable management
MCP Protocol: For seamless integration with AI assistants

The system uses an asynchronous architecture to provide high-performance, non-blocking API interactions, enabling efficient processing of multiple requests simultaneously.

🔑 API Key Management

SHODAN-MCP uses the Shodan API key stored in a .env file in the project root. This approach keeps your API key secure and separate from the code.

Get an API key: Sign up at Shodan to obtain your API key
Create .env file: Create a .env file in the project root with the following content:
```
SHODAN_API_KEY=your_api_key_here
```

The .env file is included in .gitignore to prevent your API key from being uploaded to public repositories. The project automatically loads the API key from this file using the python-dotenv library.

Security note: Never share your Shodan API key or include it in files that might be uploaded to public repositories.

🛡️ Security & Ethics

This tool is designed for legitimate security research and defensive purposes. Users are responsible for ensuring they comply with:

Applicable laws and regulations
Shodan's terms of service
Ethical standards for security research

Always obtain proper authorization before scanning or analyzing systems you don't own.

📚 Usage Notes

Some commands consume Shodan API credits (see Shodan pricing)
Results provide comprehensive intelligence for analysis
Data is presented in a structured, readable format
Advanced formatting instructions ensure clarity of technical details
For bulk operations, consider using the async batch methods to optimize performance

🔮 Upcoming Features

The following features are planned for future releases:

Markdown Report Generation: Automatically create comprehensive reports in Markdown format for all queries
Batch Processing: Process multiple queries in parallel for improved efficiency
Advanced Visualization: Visual representations of search results and networks
Docker Container: Ready-to-use containerized version for easier deployment
Cross-Platform Testing: Expanded testing and support for Windows and other platforms

👥 Contributions Welcome!

This project was created by a security enthusiast, not a professional developer. There are many areas that could benefit from improvement, and contributions of all kinds are welcome!

Areas Needing Improvement

Code Quality: Refactoring and optimization
Error Handling: More robust error handling and recovery
Documentation: Expanded examples and use cases
Testing: Unit tests and integration tests
UI Development: A simple web interface for non-programmers
Cross-Platform Support: Testing and fixes for Windows and other platforms

If you'd like to contribute, please feel free to submit pull requests or open issues with suggestions. No contribution is too small, and all help is greatly appreciated!

🐛 Troubleshooting

Issue	Solution
API Key errors	Verify your key is valid and correctly configured
Rate limiting	Implement exponential backoff or upgrade your Shodan plan
Module not found	Ensure all dependencies are installed correctly
Integration issues	Check your MCP paths and configurations
Timeout errors	Increase timeout settings for large queries

🌟 Credits

Powered by me 😇 using Shodan API - The Internet's Search Engine
Developed using Python's async architecture for optimal performance
MCP protocol specification by Anthropic

Shodan MCP Overview