Cyreslab AI Shodan MCP Server

🚀 Shodan MCP Server

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

✨ Features

• Host Information: Retrieve detailed information about a specific IP address.
• Search Function: 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
   

💻 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 query.
• 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 results (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., 'apache country:US').
• page (optional): The page number of the results (default: 1).
• facets (optional): A list of facets to include in the search results (e.g., ['country', 'org']).
• 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 results (e.g., ['ip_str', 'ports', 'location.country_name']).
• summarize (optional): Whether to return a summary of the results instead of the full data (default: false).

scan_network_range

Scan a network range (in CIDR format) to find devices. Parameters:

• cidr (required): The CIDR notation of the network range.
• 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 results.

get_ssl_certificate

Retrieve information about an SSL certificate for a specific domain. Parameters:

• domain (required): The domain to query.
• 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 results.

search_iot_devices

Find specific types of IoT devices. Parameters:

• device_type (required): The type of device to search for.
• vendor (optional): The vendor of the device.
• model (optional): The model of the device.

📚 Resources

Available Resources

• /api/host/<ip>: Get host information for a specific IP address.
• /api/search: Execute a Shodan search query.
• /api/certificate: Get SSL certificate information.
• /api/iot: Search for IoT devices.

💻 Usage Examples

Example Response for Querying Host Information

{
  "ip": "192.168.1.1",
  "hostname": "router.home",
  "ports": [80, 443],
  "protocols": ["http", "https"]
}

Example Response for Search Results

[
  {
    "ip": "10.0.0.1",
    "device_type": "router",
    "vendor": "Cisco"
  },
  {
    "ip": "10.0.0.2",
    "device_type": "camera",
    "vendor": "Axis"
  }
]

🔧 Technical Details

API Limits

• The maximum number of items returned per call is 5.
• A valid Shodan API key is required for authentication.
• The search function may be subject to rate limits.

📄 License

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

👥 Contributors

Thank you to all contributors! See CONTRIBUTORS.md for the full list.

📞 Contact

If you have any questions or feedback, please contact support@cyberlabs.com.