Shodan MCP Server

🚀 Shodan MCP Server

A Model Context Protocol (MCP) server that provides access to Shodan API functionality, allowing AI assistants to query information about internet-connected devices and services.

🚀 Quick Start

This Shodan MCP Server enables AI assistants to access Shodan API functionalities for querying information on internet-connected devices and services.

✨ Features

• Host Information: Retrieve detailed information about a specific IP address.
• Search Functionality: Search for devices and services in the Shodan database.
• Network Scanning: Scan a network range (in CIDR format) to find devices.
• SSL Certificate Information: Obtain detailed information about a domain's SSL certificate.
• IoT Device Search: Find specific types of IoT devices.

📦 Installation

1. Clone the repository:

   git clone https://github.com/Cyreslab-AI/shodan-mcp-server.git
   cd shodan-mcp-server
   

2. Install dependencies:

   npm install
   

3. Build the server:

   npm run build
   

4. Set your Shodan API key:

   export SHODAN_API_KEY="your-api-key-here"
   

5. Start the server:

   npm start
   

💻 Usage Examples

MCP Integration

This server can be integrated with Claude or other MCP-compatible AI assistants. To add it to Claude Desktop or Claude.app:

1. Add the server to your MCP settings:

   {
     "mcpServers": {
       "shodan": {
         "command": "node",
         "args": ["/path/to/shodan-mcp-server/build/index.js"],
         "env": {
           "SHODAN_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

2. Restart Claude to load the new MCP server.

Available Tools

get_host_info

Retrieve detailed information about a specific IP address.

Parameters:

• ip (required): The IP address to look up.
• max_items (optional): The maximum number of items to include in the array (default: 5).
• fields (optional): A list of fields to include in the result (e.g., ['ip_str', 'ports', 'location.country_name']).

search_shodan

Search for devices and services in the Shodan database.

Parameters:

• query (required): The Shodan search query (e.g., "web server").
• page (optional): The page number of the results.
• limit (optional): The number of results per page.

scan_network

Scan a network range to find devices.

Parameters:

• cidr (required): The CIDR range to scan (e.g., "192.168.1.0/24").

get_ssl_certificate

Obtain detailed information about a domain's SSL certificate.

Parameters:

• domain (required): The domain name to look up.

search_iot_devices

Find specific types of IoT devices.

Parameters:

• device_type (optional): A filter for the device type.
• vendor (optional): A filter for the device vendor.

📚 Documentation

Resources

Specific resources can be accessed via the following URL:

https://api.shodan.io/labs/[resource]

API Limitations

• Free API: Provides basic functionality with rate limits.
• Paid API: Offers more advanced features and higher request limits.

📄 License

This project is licensed under the MIT License.

👨‍💻 Developer Information

Developed by [Your Name].