Shodan MCP Server

🚀 shodan-mcp-server

This is a Model Context Protocol (MCP) server that provides access to the Shodan API. It allows you to programmatically query Shodan for information about devices, vulnerabilities, etc.

🚀 Quick Start

shodan-mcp-server offers a convenient way to integrate Shodan intelligence into your applications using the Model Context Protocol (MCP). It exposes several tools that enable you to query Shodan for various types of information.

✨ Features

• Host Information: Retrieve detailed information about a specific IP address.
• Search: Query Shodan's database using its search syntax.
• DNS Resolution: Resolve domain names.
• CVE Information: Obtain detailed information about specific CVE vulnerabilities.

📦 Installation

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

📚 Documentation

Configuration

1. Obtain a Shodan API key from Shodan.
2. Configure the MCP server in your MCP settings file (e.g., ~/.config/mcp/settings.json):

{
  "mcpServers": {
    "shodan": {
      "command": "node",
      "args": ["/path/to/shodan-mcp-server/build/index.js"],
      "env": {
        "SHODAN_API_KEY": "<your_shodan_api_key>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Replace <your_shodan_api_key> with your actual Shodan API key and /path/to/shodan-mcp-server with the actual path to shodan-mcp-server.

Usage with Node.js

You can use the MCP server through Node.js with the @modelcontextprotocol/sdk package:

1. Install the MCP SDK:

npm install @modelcontextprotocol/sdk

2. Call tools using the use_mcp_tool function:

import { use_mcp_tool } from '@modelcontextprotocol/sdk';

async function get_ip_info() {
    try {
        const result = await use_mcp_tool('shodan', 'get_ip_info', {
            ip: '8.8.8.8' // Example IP address
        });
        console.log(result);
    } catch (error) {
        console.error('Error:', error);
    }
}

get_ip_info();

API Documentation

get_ip_info

• Description: Retrieve detailed information about a specified IP address.
• Parameters:
  • ip (string): The IP address to query.
• Return Value: An object containing the following:
  • ip: The target IP address.
  • hostnames: An array of hostnames associated with the IP.
  • location: Geographical location information, including country, city, and latitude/longitude.
  • ASN: The Autonomous System Number and its owner.
  • ports: A list of open ports and their corresponding services.

dns_lookup

• Description: Resolve a domain name and obtain its corresponding IP address.
• Parameters:
  • domain (string): The domain name to resolve.
• Return Value: An object containing the following:
  • domain: The target domain name.
  • ips: A list of IP addresses associated with the domain.

get_vulnerabilities

• Description: Retrieve vulnerability information related to a specified IP.
• Parameters:
  • ip (string): The IP address to query.
• Return Value: An array containing the following:
  • id: The vulnerability ID.
  • title: The vulnerability title.
  • severity: The vulnerability severity level (e.g., "high", "medium", "low").

cve_info

• Description: Retrieve detailed information about a specific CVE vulnerability.
• Parameters:
  • cve_id (string): The CVE ID (e.g., "CVE-2021-XXXX").
• Return Value: An object containing the following:
  • id: The CVE ID.
  • summary: A summary of the vulnerability.
  • severity: The vulnerability severity level.
  • affected_packages: A list of affected software packages or components.

search

• Description: Query the database using Shodan's search syntax.
• Parameters:
  • query (string): The search query to execute.
• Return Value: An object containing matching results, each including:
  • ip: The IP address.
  • port: The open port.
  • service: The running service.

Project Structure

shodan-mcp-server/
├── index.js          # Main program entry
├── build/           # Build output directory
├── package.json     # Dependency management file
└── README.md        # Project documentation

Contributing

Contributors can participate in the following ways:

1. Submit issues: Report bugs or propose feature requests.
2. Submit pull requests: Fix issues or add new features. Please ensure you read and follow the project's Contribution Guidelines before submitting code.

📄 License

This project is licensed under the MIT License.