# shodan [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/w0h1v/mcp-shodan  
**GitHub Stars:** 189  
**npm Downloads (last month):** 4414  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/shodan-2

## Description
MCP server for Shodan API — device search, IP lookup, DNS, and CVE/CPE queries.

## Tools
Capabilities this server exposes over MCP:

- **ip_lookup** — Retrieve comprehensive information about an IP address, including geolocation, operating system, open ports, running services (product, version, CPE), known vulnerabilities (CVEs), SSL certificates, hostnames, and cloud provider details if available. Returns service banners and HTTP server information when present. Optional history returns historical banners; minify omits banners.
- **shodan_search** — Search Shodan's database of internet-connected devices. Returns detailed information about matching devices including services, vulnerabilities, and geographic distribution. Supports advanced search filters and returns facet statistics (default: by country). Costs 1 query credit when the query uses filters, plus 1 per page beyond the first. Use shodan_count (free) to get totals and facets without results.
- **cve_lookup** — Query detailed vulnerability information from Shodan's CVEDB. Returns comprehensive CVE details including CVSS scores (v4/v3/v2), EPSS probability and ranking, KEV status, proposed mitigations, ransomware associations, and affected products (CPEs).
- **dns_lookup** — Resolve domain names to IP addresses using Shodan's DNS service. Supports batch resolution of multiple hostnames in a single query. Returns IP addresses mapped to their corresponding hostnames.
- **reverse_dns_lookup** — Perform reverse DNS lookups to find hostnames associated with IP addresses. Supports batch lookups of multiple IP addresses in a single query. Returns all known hostnames for each IP address, with clear indication when no hostnames are found.
- **cpe_lookup** — Search for Common Platform Enumeration (CPE) entries by product name in Shodan's CVEDB. Supports pagination and can return either full CPE details or just the total count. Useful for identifying specific versions and configurations of software and hardware.
- **cves_by_product** — Search for vulnerabilities affecting specific products or CPEs. Supports filtering by KEV status, sorting by EPSS score, date ranges, and pagination. Can search by product name or CPE 2.3 identifier. Returns detailed vulnerability information including severity scores and impact assessments.
- **shodan_count** — Get the total number of Shodan results for a query, with optional facet breakdowns (e.g. by country, org, port). Free: does not consume query credits. Use search_filters to list valid filters and facets.
- **domain_info** — Get subdomains and DNS records for a domain from Shodan. Costs 1 query credit per lookup.
- **api_info** — Show the Shodan API plan, remaining query and scan credits, monitored IPs, and usage limits for the configured API key. Free: does not consume credits.
- **search_filters** — List the search filters and facets Shodan supports. Use this to build valid shodan_search and shodan_count queries and facets. Free: does not consume credits.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "shodan": {
    "command": "npx",
    "args": ["-y","@burtthecoder/mcp-shodan"],
    "env": {
      "SHODAN_API_KEY": "",
      "MCP_TRANSPORT": "",
      "MCP_HOST": "",
      "MCP_PORT": "",
      "MCP_ENDPOINT": ""
    }
  }
}
```

**Requires environment variables:** `SHODAN_API_KEY`, `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT`, `MCP_ENDPOINT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What shodan does

The shodan MCP server gives MCP-compatible AI clients access to Shodan’s internet intelligence and CVEDB services. Its read-only tools cover host reconnaissance, device discovery, DNS analysis, domain information, and vulnerability research.

An IP lookup can return open ports, detected products and versions, service banners, operating system data, geolocation, hostnames, TLS certificate details, cloud provider information, and associated CVEs. Historical banners can be requested, while a compact mode omits banner data. Device searches use Shodan query syntax and can return matching services, vulnerabilities, geographic facets, and pagination results.

The CVEDB tools provide CVSS v2, v3, and v4 scores, EPSS data, KEV status, affected CPEs, mitigations, references, and ransomware associations. Product and CPE searches can be filtered by KEV status or date and sorted by EPSS. DNS tools support forward and reverse lookups in batches, while domain information includes subdomains and DNS records.

## How it works

The server validates tool arguments before sending HTTPS requests to Shodan. Requests to the Shodan API use the configured API key; CVEDB requests do not require that key. Results are returned to the agent as structured JSON text.

stdio is the default transport and suits local desktop or command-line clients. Setting `MCP_TRANSPORT=httpStream` starts an HTTP streaming service instead. The HTTP service exposes a health endpoint at `/health` and uses `/mcp` as its default MCP path.

Most reconnaissance and CVEDB operations are free under the server’s credit accounting. Filtered `shodan_search` requests use one query credit, with an additional credit for each page after the first. `domain_info` uses one query credit per call. `shodan_count`, `ip_lookup`, DNS lookups, helper tools, and CVEDB queries do not consume query credits.

## Setup and configuration

Node.js 20 or newer and a Shodan API key are required. For a local stdio installation, run the package through `npx` and provide `SHODAN_API_KEY` in the MCP client configuration. Claude Code, Codex CLI, and Gemini CLI can register it with their respective MCP commands; Claude Desktop and VS Code can also connect through client configuration.

HTTP mode can be started with:

```sh
MCP_TRANSPORT=httpStream MCP_PORT=3000 SHODAN_API_KEY=your-key node build/index.js
```

`MCP_HOST` controls the HTTP bind address, `MCP_PORT` selects the listening port, and `MCP_ENDPOINT` changes the MCP path. The default host is `localhost`, the default port is `3000`, and the default endpoint is `/mcp`.

The HTTP transport has no built-in authentication. Keep it bound to localhost or place it behind an authenticating reverse proxy, particularly because reachable users could spend the configured Shodan account’s credits. The API key is sent only to `api.shodan.io`; lookup values are sent to Shodan.

## Tools and capabilities

- `ip_lookup`: Inspect ports, services, banners, TLS data, location, cloud details, and vulnerabilities for an IPv4 or IPv6 address.
- `shodan_search`: Search devices with Shodan filters, paging, and facet breakdowns.
- `shodan_count`: Get query totals and facets without retrieving result records.
- `domain_info`: Retrieve subdomains and DNS records for a domain.
- `dns_lookup` and `reverse_dns_lookup`: Resolve hostnames or find hostnames for IP addresses, including batch requests.
- `cve_lookup`: Retrieve detailed information for one CVE.
- `cpe_lookup`: Find CPE entries for a product, with pagination or count-only output.
- `cves_by_product`: Find vulnerabilities by product name or CPE with filtering and EPSS sorting.
- `search_filters`: List valid Shodan filters and facets.
- `api_info`: Show plan details and remaining query and scan credits.

## Limitations and notes

Shodan search filters may require a membership or paid API plan. Shodan also permits roughly one request per second, so clients may need to retry after rate-limit responses. Invalid API keys produce authorization errors. This is an independent project and is not affiliated with Shodan.

_Full upstream README: https://allmcps.com/mcp/shodan-2/readme_