Shodan MCP Server

1# Shodan MCP Server
2 
3[![smithery badge](https://smithery.ai/badge/@burtthecoder/mcp-shodan)](https://smithery.ai/server/@burtthecoder/mcp-shodan)
4 
5A Model Context Protocol (MCP) server for querying the [Shodan API](https://shodan.io) and [Shodan CVEDB](https://cvedb.shodan.io). This server provides comprehensive access to Shodan's network intelligence and security services, including IP reconnaissance, DNS operations, vulnerability tracking, and device discovery. All tools provide structured, formatted output for easy analysis and integration.
6 
7<a href="https://glama.ai/mcp/servers/79uakvikcj"><img width="380" height="200" src="https://glama.ai/mcp/servers/79uakvikcj/badge" /></a>
8 
9## Quick Start (Recommended)
10 
11### Installing via Smithery
12 
13To install Shodan Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@burtthecoder/mcp-shodan):
14 
15```bash
16npx -y @smithery/cli install @burtthecoder/mcp-shodan --client claude
17```
18 
19### Installing Manually
201. Install the server globally via npm:
21```bash
22npm install -g @burtthecoder/mcp-shodan
23```
24 
252. Add to your Claude Desktop configuration file:
26```json
27{
28  "mcpServers": {
29    "shodan": {
30      "command": "mcp-shodan",
31      "env": {
32        "SHODAN_API_KEY": "your-shodan-api-key"
33      }
34    }
35  }
36}
37```
38 
39Configuration file location:
40- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
41- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
42 
433. Restart Claude Desktop
44 
45## Alternative Setup (From Source)
46 
47If you prefer to run from source or need to modify the code:
48 
491. Clone and build:
50```bash
51git clone https://github.com/BurtTheCoder/mcp-shodan.git
52cd mcp-shodan
53npm install
54npm run build
55```
56 
572. Add to your Claude Desktop configuration:
58```json
59{
60  "mcpServers": {
61    "shodan": {
62      "command": "node",
63      "args": ["/absolute/path/to/mcp-shodan/build/index.js"],
64      "env": {
65        "SHODAN_API_KEY": "your-shodan-api-key"
66      }
67    }
68  }
69}
70```
71 
72## Features
73 
74- **Network Reconnaissance**: Query detailed information about IP addresses, including open ports, services, and vulnerabilities
75- **DNS Operations**: Forward and reverse DNS lookups for domains and IP addresses
76- **Vulnerability Intelligence**: Access to Shodan's CVEDB for detailed vulnerability information, CPE lookups, and product-specific CVE tracking
77- **Device Discovery**: Search Shodan's database of internet-connected devices with advanced filtering
78 
79## Tools
80 
81### 1. IP Lookup Tool
82- Name: `ip_lookup`
83- Description: Retrieve comprehensive information about an IP address, including geolocation, open ports, running services, SSL certificates, hostnames, and cloud provider details if available
84- Parameters:
85  * `ip` (required): IP address to lookup
86- Returns:
87  * IP Information (address, organization, ISP, ASN)
88  * Location (country, city, coordinates)
89  * Services (ports, protocols, banners)
90  * Cloud Provider details (if available)
91  * Associated hostnames and domains
92  * Tags
93 
94### 2. Shodan Search Tool
95- Name: `shodan_search`
96- Description: Search Shodan's database of internet-connected devices
97- Parameters:
98  * `query` (required): Shodan search query
99  * `max_results` (optional, default: 10): Number of results to return
100- Returns:
101  * Search summary with total results
102  * Country-based distribution statistics
103  * Detailed device information including:
104    - Basic information (IP, organization, ISP)
105    - Location data
106    - Service details
107    - Web server information
108    - Associated hostnames and domains
109 
110### 3. CVE Lookup Tool
111- Name: `cve_lookup`
112- Description: Query detailed vulnerability information from Shodan's CVEDB
113- Parameters:
114  * `cve` (required): CVE identifier in format CVE-YYYY-NNNNN (e.g., CVE-2021-44228)
115- Returns:
116  * Basic Information (ID, published date, summary)
117  * Severity Scores:
118    - CVSS v2 and v3 with severity levels
119    - EPSS probability and ranking
120  * Impact Assessment:
121    - KEV status
122    - Proposed mitigations
123    - Ransomware associations
124  * Affected products (CPEs)
125  * References
126 
127### 4. DNS Lookup Tool
128- Name: `dns_lookup`
129- Description: Resolve domain names to IP addresses using Shodan's DNS service
130- Parameters:
131  * `hostnames` (required): Array of hostnames to resolve
132- Returns:
133  * DNS resolutions mapping hostnames to IPs
134  * Summary of total lookups and queried hostnames
135 
136### 5. Reverse DNS Lookup Tool
137- Name: `reverse_dns_lookup`
138- Description: Perform reverse DNS lookups to find hostnames associated with IP addresses
139- Parameters:
140  * `ips` (required): Array of IP addresses to lookup
141- Returns:
142  * Reverse DNS resolutions mapping IPs to hostnames
143  * Summary of total lookups and results
144 
145### 6. CPE Lookup Tool
146- Name: `cpe_lookup`
147- Description: Search for Common Platform Enumeration (CPE) entries by product name
148- Parameters:
149  * `product` (required): Name of the product to search for
150  * `count` (optional, default: false): If true, returns only the count of matching CPEs
151  * `skip` (optional, default: 0): Number of CPEs to skip (for pagination)
152  * `limit` (optional, default: 1000): Maximum number of CPEs to return
153- Returns:
154  * When count is true: Total number of matching CPEs
155  * When count is false: List of CPEs with pagination details
156 
157### 7. CVEs by Product Tool
158- Name: `cves_by_product`
159- Description: Search for vulnerabilities affecting specific products or CPEs
160- Parameters:
161  * `cpe23` (optional): CPE 2.3 identifier (format: cpe:2.3:part:vendor:product:version)
162  * `product` (optional): Name of the product to search for CVEs
163  * `count` (optional, default: false): If true, returns only the count of matching CVEs
164  * `is_kev` (optional, default: false): If true, returns only CVEs with KEV flag set
165  * `sort_by_epss` (optional, default: false): If true, sorts CVEs by EPSS score
166  * `skip` (optional, default: 0): Number of CVEs to skip (for pagination)
167  * `limit` (optional, default: 1000): Maximum number of CVEs to return
168  * `start_date` (optional): Start date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS)
169  * `end_date` (optional): End date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS)
170- Notes:
171  * Must provide either cpe23 or product, but not both
172  * Date filtering uses published time of CVEs
173- Returns:
174  * Query information
175  * Results summary with pagination details
176  * Detailed vulnerability information including:
177    - Basic information
178    - Severity scores
179    - Impact assessments
180    - References
181 
182## Requirements
183 
184- Node.js (v20 or later)
185- A valid [Shodan API Key](https://account.shodan.io/)
186 
187## Troubleshooting
188 
189### API Key Issues
190 
191If you see API key related errors (e.g., "Request failed with status code 401"):
192 
1931. Verify your API key:
194   - Must be a valid Shodan API key from your [account settings](https://account.shodan.io/)
195   - Ensure the key has sufficient credits/permissions for the operation
196   - Check for extra spaces or quotes around the key in the configuration
197   - Verify the key is correctly set in the SHODAN_API_KEY environment variable
198 
1992. Common Error Codes:
200   - 401 Unauthorized: Invalid API key or missing authentication
201   - 402 Payment Required: Out of query credits
202   - 429 Too Many Requests: Rate limit exceeded
203 
2043. Configuration Steps:
205   a. Get your API key from [Shodan Account](https://account.shodan.io/)
206   b. Add it to your configuration file:
207      ```json
208      {
209        "mcpServers": {
210          "shodan": {
211            "command": "mcp-shodan",
212            "env": {
213              "SHODAN_API_KEY": "your-actual-api-key-here"
214            }
215          }
216        }
217      }
218      ```
219   c. Save the config file
220   d. Restart Claude Desktop
221 
2224. Testing Your Key:
223   - Try a simple query first (e.g., dns_lookup for "google.com")
224   - Check your [Shodan account dashboard](https://account.shodan.io/) for credit status
225   - Verify the key works directly with curl:
226     ```bash
227     curl "https://api.shodan.io/dns/resolve?hostnames=google.com&key=your-api-key"
228     ```
229 
230### Module Loading Issues
231 
232If you see module loading errors:
2331. For global installation: Use the simple configuration shown in Quick Start
2342. For source installation: Ensure you're using Node.js v18 or later
235 
236## Development
237 
238Build the project:
239```bash
240npm install
241npm run build
242```
243 
244Test interactively with FastMCP's built-in dev tool:
245```bash
246npx fastmcp dev build/index.js
247```
248 
249## Error Handling
250 
251The server includes comprehensive error handling for:
252- Invalid API keys
253- Rate limiting
254- Network errors
255- Invalid input parameters
256- Invalid CVE formats
257- Invalid CPE lookup parameters
258- Invalid date formats
259- Mutually exclusive parameter validation
260 
261## Version History
262 
263- v1.1.0: Migrated from raw `@modelcontextprotocol/sdk` to [FastMCP](https://github.com/punkpeye/fastmcp) — modular tool files, automatic schema validation, simplified error handling
264- v1.0.12: Added reverse DNS lookup and improved output formatting
265- v1.0.7: Added CVEs by Product search functionality and renamed vulnerabilities tool to cve_lookup
266- v1.0.6: Added CVEDB integration for enhanced CVE lookups and CPE search functionality
267- v1.0.0: Initial release with core functionality
268 
269## Contributing
270 
2711. Fork the repository
2722. Create a feature branch (`git checkout -b feature/amazing-feature`)
2733. Commit your changes (`git commit -m 'Add amazing feature'`)
2744. Push to the branch (`git push origin feature/amazing-feature`)
2755. Open a Pull Request
276 
277## License
278 
279This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
280