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
- 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
-
Clone the repository:
git clone https://github.com/X3r0K/Shodan-MCP-Server.git cd shodan-mcp-server -
Install the dependencies:
npm install -
Build the project:
npm run build
Configuration
-
Obtain a Shodan API key from Shodan.
-
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-serverwith 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.
-
Install the MCP SDK:
npm install @modelcontextprotocol/sdk -
Use the
use_mcp_toolfunction 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