MCP Shodan

🚀 MCP Shodan Server Module

This project is an MCP (Malicious Code Protection) server module built using the Shodan API. It supports a variety of functions, including DNS resolution, reverse DNS lookup, IPv4 geolocation, CVE and CPE vulnerability information queries, etc.

🚀 Quick Start

📦 Installation

1. Global installation:

   npm install mcp-shodan@latest -g
   

2. Create a configuration file:

   # Create config.json at the default location
   mcp-shodan init-config
   # Create a configuration file at a custom path
   mcp-shodan init-config --path /custom/path/config.json
   

⚙️ Configuration

Add the following content to your Claude Desktop configuration file:

{
  "mcpServers": {
    "shodan": {
      "command": "mcp-shodan",
      "env": {
        "SHODAN_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

▶️ Start

1. Start with the globally installed configuration:

   mcp-shodan start
   

2. Start with the configuration at a custom path:

   mcp-shodan start --path /custom/path/config.json
   

✨ Features

💻 DNS Resolution

{
  "dns_lookup": {
    "hostnames": ["google.com", "example.com"]
  }
}

The return format is:

{
  "resolve": {
    "google.com": "172.217.14.206",
    "example.com": "93.184.216.3"
  }
}

💻 Reverse DNS Lookup

{
  "reverse_dns": {
    "ips": ["172.217.14.206", "93.184.216.3"]
  }
}

The return format is:

{
  "reverse": {
    "172.217.14.206": "google.com",
    "93.184.216.3": "example.com"
  }
}

💻 IPv4 Geolocation

{
  "ip_geo": {
    "ips": ["172.217.14.206", "93.184.216.3"]
  }
}

The return format is:

[
  {
    "ip": "172.217.14.206",
    "city": "Mountain View",
    "region": "California",
    "country_name": "United States",
    "latitude": 37.3568,
    "longitude": -122.090
  },
  {
    "ip": "93.184.216.3",
    "city": "Ermont",
    "region": "Île-de-France",
    "country_name": "France",
    "latitude": 48.95,
    "longitude": 2.07
  }
]

💻 CVE Query

{
  "cve_search": {
    "cves": ["CVE-2013-0809", "CVE-2015-5606"]
  }
}

The return format is:

[
  {
    "cve_id": "CVE-2013-0809",
    "summary": "Java deserialization vulnerability affecting multiple versions of Oracle Java SE.",
    "severity": "High Risk"
  },
  {
    "cve_id": "CVE-2015-5606",
    "summary": "Adobe Flash Player remote code execution vulnerability.",
    "severity": "Severe"
  }
]

💻 CPE Matching

{
  "cpe_match": {
    "cpes": ["cpe:/a:apple:safari", "cpe:/o:microsoft:windows"]
  }
}

The return format is:

[
  {
    "cpe": "cpe:/a:apple:safari",
    "vendors": ["Apple"],
    "products": ["Safari"]
  },
  {
    "cpe": "cpe:/o:microsoft:windows",
    "vendors": ["Microsoft"],
    "products": ["Windows"]
  }
]

⚠️ Error Handling

💥 Parameter Error

{
  "error": {
    "code": 400,
    "message": "Invalid parameter format."
  }
}

💥 API Call Failure

{
  "error": {
    "code": 503,
    "message": "Unable to connect to the Shodan service."
  }
}

📁 Project Structure

mcp-shodan/
├── src/                 # Source code directory
│   ├── main.js          # Main program entry
│   └── modules/         # Function modules
│       ├── dns_lookup.js    # DNS resolution function
│       └── reverse_dns.js  # Reverse DNS lookup function
├── config/              # Configuration file directory
│   └── config.json      # Default configuration file
└── package.json        # Project dependency management

📖 Usage Instructions

⚙️ Initialize Configuration File

mcp-shodan init-config [--path <path>]
# Example:
$ mcp-shodan init-config --path /custom/path

▶️ Start Service

mcp-shodan start [--path <path>]
# Example:
$ mcp-shodan start

📜 Version History

🤝 Contribution Guidelines

💻 Submit Code

git clone https://github.com/yourusername/mcp-shodan.git
cd mcp-shodan
npm run dev

🐛 Create an Issue

Create a new issue on GitHub: https://github.com/yourusername/mcp-shodan/issues

📄 License

This project uses the MIT license. Please refer to the LICENSE file for specific details.

Thank you for your support of this project! If you have any questions, please feel free to contact the maintainers.