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, and more.

Table of Contents

• Introduction
• Installation
• Configuration
• Usage with Node.js
• API Documentation
  • get_ip_info
  • dns_lookup
  • get_vulnerabilities
  • cve_info
  • search
• Project Structure
• Contributing
• License

Introduction

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

Features

Host Information: Get detailed information about an IP address Search: Query Shodan's database using their search syntax DNS Lookup: Resolve domain names CVE Information: Get details 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
   

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 the shodan-mcp-server directory.

Usage with Node.js

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

1. Install the MCP SDK:

   npm install @modelcontextprotocol/sdk
   

2. Use the use_mcp_tool function to call the tools:

   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

Get 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 DNS lookups for a given domain.

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 a list of vulnerabilities associated with the IP address.

cve_info

Retrieve information about a specific CVE ID.

Input:

{
  "cve": "string" // The CVE ID to query
}

Output:

A JSON object containing information about the CVE ID.

search

Search Shodan for devices matching a query.

Input:

{
  "query": "string" // The search query
}

Output:

A JSON object containing a list of devices matching the query.

Project Structure

shodan-mcp-server/
├── .gitignore
├── package.json
├── README.md
├── tsconfig.json
└── src/
    ├── index.ts
    └── index.mts

License

MIT