Shodan MCP Server

A Model Context Protocol (MCP) server that provides access to Shodan's internet scanning capabilities through a standardized interface.

Overview

This server implements the Model Context Protocol to expose Shodan's powerful internet scanning and reconnaissance capabilities. It provides a standardized interface for querying Shodan's database of internet-connected devices, services, and vulnerabilities.

Features

Search Capabilities: Query Shodan's database using advanced search filters
DNS Lookup: Resolve domain names and get detailed DNS information
CVE Information: Get detailed information about Common Vulnerabilities and Exposures
Get Vulnerabilities: Get detailed infor Vulnerabilities related to an IP address
Standardized Interface: Uses MCP protocol for consistent communication
Environment Variable Support: Secure API key management through environment variables

Prerequisites

Node.js (v14 or higher)
npm (v6 or higher)
Shodan API key

Installation

Clone the repository:

git clone https://github.com/X3r0K/Shodan-MCP-Server-Inspector.git
cd shodan-mcp-server-Inspector

Install dependencies:
```
npm install
```
Create a .env.local file in the root directory and add your Shodan API key:
```
SHODAN_API_KEY=your_api_key_here
```

Usage

Starting the Server

Build the server:
```
npm run build
```
Start the server:
```
node build/index.js
```

Available Tools

Search Tool
- Query: Search for devices and services using Shodan's search syntax
- Example: log4j country:US city:Atlanta
- Returns: List of matching devices with detailed information
DNS Lookup Tool
- Query: Domain name to resolve
- Example: example.com
- Returns: DNS records and related information
CVE Info Tool
- Query: CVE identifier
- Example: CVE-2021-44228
- Returns: Detailed vulnerability information

Example Queries

// Search for Log4j vulnerable systems in the US
{
  "query": "log4j country:US"
}

// DNS lookup for a domain
{
  "query": "example.com"
}

// Get CVE information
{
  "query": "CVE-2021-44228"
}

Using the MCP Inspector

You can use the MCP inspector to interact with the server directly:

Install the MCP inspector:

npm install -g @modelcontextprotocol/inspector

Run the inspector with your server:

npx @modelcontextprotocol/inspector build/index.js

The inspector provides an interactive interface to:

Test all available tools
View tool documentation
Debug server responses
Monitor server status

Environment Variables

SHODAN_API_KEY: Your Shodan API key (required)
PORT: Server port (optional, defaults to 3000)
LOG_LEVEL: Logging level (optional, defaults to 'info')

Error Handling

The server implements comprehensive error handling for:

Invalid API keys
Rate limiting
Network issues
Invalid queries
Server errors

Security Considerations

API Key Protection:
- Never commit API keys to version control
- Use environment variables for sensitive data
- Rotate API keys regularly
Rate Limiting:
- Respect Shodan's API rate limits
- Implement client-side rate limiting
Data Privacy:
- Filter sensitive information from responses
- Implement access controls as needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Shodan for providing the API
Model Context Protocol team for the MCP specification