Shodan-MCP-Server-Inspector

# 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 1. Clone the repository: ```bash git clone https://github.com/X3r0K/Shodan-MCP-Server-Inspector.git cd shodan-mcp-server-Inspector ``` 2. Install dependencies: ```bash npm install ``` 3. Create a `.env.local` file in the root directory and add your Shodan API key: ```bash SHODAN_API_KEY=your_api_key_here ``` ## Usage ### Starting the Server 1. Build the server: ```bash npm run build ``` 2. Start the server: ```bash node build/index.js ``` ### Available Tools 1. **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 2. **DNS Lookup Tool** - Query: Domain name to resolve - Example: `example.com` - Returns: DNS records and related information 3. **CVE Info Tool** - Query: CVE identifier - Example: `CVE-2021-44228` - Returns: Detailed vulnerability information ### Example Queries ```javascript // 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: 1. Install the MCP inspector: ```bash npm install -g @modelcontextprotocol/inspector ``` 2. Run the inspector with your server: ```bash 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 1. API Key Protection: - Never commit API keys to version control - Use environment variables for sensitive data - Rotate API keys regularly 2. Rate Limiting: - Respect Shodan's API rate limits - Implement client-side rate limiting 3. 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