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 device information, vulnerabilities, and other relevant data.

🚀 Quick Start

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

✨ Features

• Host Information: Retrieve detailed information about a specific IP address.
• Search: Conduct queries using Shodan's database 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 the 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 your actual path.

Usage with Node.js

const { Client } = require('mcp-client');

async function main() {
    const client = new Client({
        server: 'http://localhost:3000'
    });

    try {
        // Example: Query Shodan
        const response = await client.query('example query');
        console.log(response);
    } catch (error) {
        console.error(error);
    }
}

main();

API Documentation

get_ip_info

• Description: Retrieve detailed information about a specific IP address.
• Parameters:
  • ip (string): The IP address to query.
• Return Value:
  • An object containing detailed information about the IP.

dns_lookup

• Description: Resolve a domain name.
• Parameters:
  • domain (string): The domain name to resolve.
• Return Value:
  • An array containing the list of resolved IP addresses.

get_vulnerabilities

• Description: Retrieve vulnerability information related to a specific IP.
• Parameters:
  • ip (string): The IP address to query.
• Return Value:
  • An array containing information about relevant vulnerabilities.

cve_info

• Description: Retrieve detailed information about a specific CVE vulnerability.
• Parameters:
  • cve_id (string): The CVE ID to query.
• Return Value:
  • An object containing detailed information about the CVE.

search

• Description: Conduct a search using Shodan query syntax.
• Parameters:
  • query (string): The search query string.
• Return Value:
  • An array containing information about the search results.

Project Structure

shodan-mcp-server/
├── src/
│   ├── server.js          # Main server file
│   └── routes/           # Route definitions
│       └── shodanRoutes.js   # Shodan-related routes
├── package.json        # Project dependencies and scripts
└── README.md           # Project documentation

Contributing

Contributions to this project, including code contributions and issue reporting, are welcome. Please refer to the contribution guidelines in the GitHub repository.

License

This project is licensed under the MIT License.