# Shodan MCP

> Shodan MCP connects your AI client directly to Shodan's massive database of internet-connected devices. Use it to scan for exposed services, analyze network ports, and discover vulnerabilities across the global IoT landscape. Get detailed reports on specific IP addresses or search by OS, product, or country.

## Overview
- **Category:** security-compliance
- **Price:** Free
- **Tags:** cybersecurity, network-scanning, threat-intelligence, open-ports, banner-grabbing, attack-surface

## Description

This MCP lets you treat the entire internet like a searchable database. Instead of running separate tools—one for DNS lookups, another for checking banners, and yet another for finding open ports—you just ask your AI client. It handles connecting to Shodan's search engine automatically.

Need to check what services are exposed by an IP address? You can get a full breakdown: open ports, running hostnames, geographic location, and operating system details. Want to track down specific types of devices? You can filter searches by product name like 'nginx' or OS type like 'Windows'. Even if you just want to know your own external IP for firewall rules, the MCP handles that query instantly. Because Vinkius hosts this Shodan MCP, all these advanced networking tools are available in one place, letting you run complex network investigations without switching catalogs.

## Tools

### get_account_info
Checks your current Shodan account limits, showing remaining usage credits for the service.

### get_api_info
Retrieves specific details about your API plan and associated billing information.

### dns_resolve
Converts a list of domain names (hostnames) into their corresponding IP addresses.

### get_facets
Lists available search filters and groupings, helping you build complex query logic like grouping by country or OS.

### get_host_info
Pulls all open port data, hostnames, location, and service banners for a single IP address.

### get_host_count
Estimates the total number of results that would match a specific search query before running the full scan.

### get_my_ip
Identifies and returns your current public, external IP address for network documentation.

### get_ports
Provides a definitive list of all ports that Shodan actively scans and monitors across the internet.

### reverse_dns
Converts known IP addresses back into their associated domain names (hostnames).

### search_hosts
Conducts a broad search across the internet using powerful filters like product, vulnerability ID, or country code.

## Prompt Examples

**Prompt:** 
```
Search for nginx servers in Brazil.
```

**Response:** 
```
Found 125,000+ nginx servers in Brazil. Top results show servers in São Paulo, Rio de Janeiro and Brasília running nginx versions 1.18 through 1.25. Common ports: 80, 443, 8080.
```

**Prompt:** 
```
Look up info for IP 8.8.8.8.
```

**Response:** 
```
8.8.8.8 (Google Public DNS): Located in Mountain View, CA, US. Organization: Google LLC. Open ports: 53 (DNS), 443 (HTTPS). Services: DNS server, DoH (DNS over HTTPS). Hostnames: dns.google.
```

**Prompt:** 
```
Resolve google.com and github.com to IPs.
```

**Response:** 
```
DNS resolution: google.com → 142.250.189.14, github.com → 140.82.121.4. Use get_host_info for detailed information on any IP address.
```

## Capabilities

### Search for Exposed Devices
You can search across the internet using filters like country code, product name, or specific operating system.

### Get Detailed Host Info
Fetch a complete report on any IP address, including all open ports, banners, and associated vulnerability data.

### Resolve Hostnames to IPs
Translate one or more domain names into their corresponding numeric IP addresses.

### Check Usage Limits
Run a check to monitor your remaining query credits and API plan status for the Shodan service.

## Use Cases

### Mapping a Target Company's Infrastructure
A security analyst needs to understand all internet-facing assets for a new client. They prompt their agent to 'Search for open ports across the target company's IP range, filtering by country and OS.' The agent uses search_hosts to return hundreds of potential entry points, which are then refined using get_host_info.

### Investigating a Suspicious Domain
A team noticed an odd domain name. They first use dns_resolve to confirm the IP address, and then immediately run reverse_dns on that IP to see if any other hostnames are associated with it. This quickly builds a picture of potential ownership.

### Auditing Internal Exposure
A sysadmin wants to know which services their own network exposes inadvertently. They run get_my_ip and then use that IP for a detailed host info check, identifying misconfigured ports or unneeded banners.

### Analyzing IoT Device Trends
An IoT analyst needs to see how many 'Nest' cameras are exposed in specific regions. They run search_hosts using the product filter and limit by a country code, giving them actionable data on device distribution.

## Benefits

- You stop guessing what's out there. By running a search query, you can find specific devices by product (e.g., 'apache') or vulnerability ID, allowing precise threat hunting.
- No more single-point checks. You get a comprehensive report on any IP address—open ports, location, OS, and service banners—all in one data dump using the detailed host info tool.
- Quickly check your own network boundaries with get_my_ip to confirm what external services are visible to the outside world. This is great for compliance checks.
- Save time on reconnaissance. Instead of running multiple manual lookups, you use dns_resolve or reverse_dns to map out an entire domain’s infrastructure instantly.
- Know your limits before you start. Use get_account_info to monitor usage credits and ensure your AI client doesn't fail halfway through a major scan.

## How It Works

The bottom line is that this MCP lets you run advanced network discovery queries using simple, natural language prompts.

1. First, subscribe to this MCP in Vinkius and enter your unique Shodan API Key into your AI client.
2. Next, tell your agent exactly what you're looking for—for example, 'Find all open SSH ports running Debian in Germany.'
3. The system runs the query through Shodan and returns structured data showing matching IPs, services, and relevant vulnerability details.

## Frequently Asked Questions

**How does Shodan MCP help me find vulnerabilities?**
It helps by allowing you to search for devices using vulnerability identifiers (vuln:CVE-...) and then retrieving detailed host info that includes known service banners.

**Can I use the Shodan MCP to check my own IP address?**
Yes. Use get_my_ip to confirm your current public IP, which is useful for documenting firewall rules and access control lists.

**What if I only have a list of domain names? How do I start the scan?**
Start with dns_resolve. This tool takes your comma-separated hostnames and converts them into IP addresses, which you can then use for reverse_dns or get_host_info.

**Is this MCP better than running a traditional port scanner?**
Yes, because it uses Shodan's index of millions of devices. It gives you global visibility across the internet, not just what your local machine can reach.

**How do I check my usage credits with Shodan MCP?**
Use get_account_info to run a quick check on your remaining query credits and API plan details before launching any major search operation.