Shodan MCP Server
About
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.
Details
- Author
- X3r0K
- GitHub stars
- 3
- Downloads
- 195
- Categories
- Search, Security, API, Other
Jump to
- Query detailed host information by IP address
- Perform DNS lookups for domain names
- Retrieve CVE details for specific vulnerabilities
- Track vulnerabilities associated with an IP address
- Search Shodan’s database using their search syntax
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Shodan MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install the server from the repository, configure it with your Shodan API key as an environment variable (SHODAN_API_KEY), and use MCP client tools to call functions such as get_ip_info, dns_lookup, get_vulnerabilities, cve_info, and search. Example usage with the @modelcontextprotocol/sdk is provided.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"shodan mcp server": {
"shodan-mcp-server-x3r0k": {
"command": "docker",
"args": [
"run",
"-e",
"SHODAN_API_KEY=your_api_key_here",
"-p",
"3000:3000",
"shodan-mcp-server"
]
}
}
}
}McpServers
{
"shodan-mcp-server-x3r0k": {
"command": "docker",
"args": [
"run",
"-e",
"SHODAN_API_KEY=your_api_key_here",
"-p",
"3000:3000",
"shodan-mcp-server"
]
}
}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
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
