Shodan MCP Server

🚀 shodan-mcp-server

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 a variety of tools that let you query Shodan for various types of information.

✨ Features

• Host Information: Retrieve detailed information about a specific IP address.
• Search: Query using the search syntax in the Shodan database.
• 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 in conjunction with Node.js by leveraging 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 getIpInfo(ip) {
  const result = await use_mcp_tool('shodan', 'get_ip_info', { ip });
  console.log(result);
}

getIpInfo('8.8.8.8');

API Documentation

get_ip_info

Retrieve detailed information about a specific IP address. Input:

{
  "ip": "string" // The IP address to query
}

Output: A JSON object containing information about the IP address.

dns_lookup

Perform a DNS lookup on a given domain name. Input:

{
  "hostname": "string" // The hostname to resolve
}

Output: A JSON object containing the resolved IP address.

get_vulnerabilities

Track vulnerabilities associated with a specific IP address. Input:

{
  "ip": "string" // The IP address to query for vulnerabilities
}

Output: A JSON object containing information about relevant vulnerabilities.

cve_info

Retrieve detailed information about a specific CVE vulnerability. Input:

{
  "cve_id": "string" // The CVE identifier to query
}

Output: A JSON object containing detailed information about the CVE vulnerability.

search

Search the Shodan database based on filtering criteria. Input:

{
  "query": "string", // Search criteria
  "page": number,    // Current page number
  "limit": number    // Limit on the number of results
}

Output: A JSON array containing search results, with each result including device and service information.

Project Structure

project/
├── package.json          # File containing project dependencies and scripts
├── index.js              # Main program entry point
└── build/                # Directory generated by the build

Contributing

Contributions to this project are welcome! Please refer to the How to Contribute document for specific steps.

📄 License

This project is licensed under the MIT License. For more details, see the LICENSE file.