What is Shodan Mcp Server Inspector

Shodan-MCP-Server-Inspector is a Model Context Protocol (MCP) server that provides programmatic access to the Shodan API, allowing users to query information about internet-connected devices, vulnerabilities, and more.

Use cases

Use cases include querying for specific devices or services, performing DNS lookups for domain names, retrieving information on known vulnerabilities, and conducting reconnaissance for security assessments.

How to use

To use Shodan-MCP-Server-Inspector, clone the repository, install the dependencies, set up your Shodan API key in a .env.local file, build the server, and then start it to access various tools for searching devices, performing DNS lookups, and retrieving CVE information.

Key features

Key features include advanced search capabilities, DNS lookup functionality, detailed CVE information, vulnerability retrieval related to IP addresses, a standardized interface using MCP protocol, and secure API key management through environment variables.

Where to use

Shodan-MCP-Server-Inspector can be used in cybersecurity, network monitoring, vulnerability assessment, and research fields where understanding internet-connected devices and their vulnerabilities is critical.

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:

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

2. Install dependencies:

   npm install
   

3. 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

1. Build the server:

   npm run build
   

2. Start the server:

   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

// 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:

npm install -g @modelcontextprotocol/inspector

2. 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

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