Skip to content
Back to search

mcp-shodan

SkillWorks with CodexGitHub

MCP server for Shodan — search internet-connected devices, IP reconnaissance, DNS lookups, and CVE/CPE vulnerability intelligence. Works with Claude Code, Codex, Gemini CLI, and Claude Desktop.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/w0h1v/mcp-shodan with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/w0h1v/mcp-shodan'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/w0h1v--mcp-shodan/badge.svg)](/listings/w0h1v--mcp-shodan)

HTML

<a href="/listings/w0h1v--mcp-shodan"><img src="/api/listings/w0h1v--mcp-shodan/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing via Claude Code

claude mcp add --transport stdio --env SHODAN_API_KEY=your-shodan-api-key shodan -- npx -y @burtthecoder/mcp-shodan

Installing via Codex CLI

codex mcp add shodan --env SHODAN_API_KEY=your-shodan-api-key -- npx -y @burtthecoder/mcp-shodan

Installing via Gemini CLI

gemini mcp add -e SHODAN_API_KEY=your-shodan-api-key shodan npx -y @burtthecoder/mcp-shodan

Installing via Smithery

To install Shodan Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@burtthecoder/mcp-shodan):

npx -y @smithery/cli install @burtthecoder/mcp-shodan --client claude

Installing Manually

1. Install the server globally via npm:

npm install -g @burtthecoder/mcp-shodan

2. Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "shodan": {
      "command": "mcp-shodan",
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key"
      }
    }
  }
}

Configuration file location: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

3. Restart Claude Desktop

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 146 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img alt="MCP Shodan: network intelligence for AI agents. Internet reconnaissance, DNS intelligence and CVE analysis over the Model Context Protocol." src="docs/assets/banner.webp" width="100%">
  3. </p>
  4. <p align="center">
  5. <a href="https://www.npmjs.com/package/@burtthecoder/mcp-shodan"><img alt="npm version" src="https://img.shields.io/npm/v/@burtthecoder/mcp-shodan"></a>
  6. <a href="https://github.com/w0h1v/mcp-shodan/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/w0h1v/mcp-shodan/actions/workflows/ci.yml/badge.svg"></a>
  7. <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
  8. <img alt="Node 20 or newer" src="https://img.shields.io/badge/node-%E2%89%A520-339933">
  9. <a href="https://registry.modelcontextprotocol.io"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP-Registry-7c3aed"></a>
  10. </p>
  11. <p align="center">
  12. <a href="#quickstart">Quickstart</a> ·
  13. <a href="#tools">Tools</a> ·
  14. <a href="#http-streaming-transport">HTTP</a> ·
  15. <a href="#security">Security</a> ·
  16. <a href="#troubleshooting">Troubleshooting</a> ·
  17. <a href="https://w0h1v.github.io/mcp-shodan/">Docs</a>
  18. </p>
  19. **mcp-shodan** is an [MCP](https://modelcontextprotocol.io) server that gives AI agents access to the [Shodan API](https://developer.shodan.io/api) and [Shodan CVEDB](https://cvedb.shodan.io). Hand your agent an IP, hostname, search query, product or CVE and get back what an analyst would look at: open ports and banners, TLS certificates, DNS, and vulnerability severity with EPSS and KEV status.
  20. > [!NOTE]
  21. > Independent project, not affiliated with Shodan. You need your own [Shodan API key](https://account.shodan.io/).
  22. ## Highlights
  23. - **Host reconnaissance.** Open ports, products and versions, known CVEs, TLS certificate details (fingerprint, JARM, JA3S), cloud provider and banner history for any IPv4 or IPv6 address.
  24. - **Device search.** Shodan query syntax with paging and facet breakdowns (country, org, port, vuln and more), plus a free count-only mode for sizing a query.
  25. - **Vulnerability intelligence.** CVE details with CVSS v4/v3/v2, EPSS and KEV; CVEs by product or CPE, sortable by EPSS. CVEDB is free and doesn't spend query credits.
  26. - **DNS.** Subdomains and DNS records for a domain, and forward and reverse lookups for many names or IPs in one call.
  27. - **Credit-aware.** Free tools are marked as free, and `api_info` shows the credits left on your plan.
  28. - **Two transports.** stdio for desktop clients, HTTP streaming for a shared service.
  29. - **Tested.** Unit tests with a mocked Shodan API run in CI on Node 20, 22 and 24.
  30. ## How it works
  31. ```mermaid
  32. flowchart LR
  33. A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-shodan"]
  34. S -->|"validate input,<br/>HTTPS + API key"| SH["Shodan REST API"]
  35. S -->|"HTTPS, no key"| C["Shodan CVEDB"]
  36. SH -->|"JSON"| S
  37. C -->|"JSON"| S
  38. S -->|"structured JSON text"| A
  39. ```
  40. ## Quickstart
  41. **Requirements:** Node.js 20 or newer and a Shodan API key.
  42. ```sh
  43. # Claude Code
  44. claude mcp add --transport stdio --env SHODAN_API_KEY=your-key shodan -- npx -y @burtthecoder/mcp-shodan
  45. # Codex CLI
  46. codex mcp add shodan --env SHODAN_API_KEY=your-key -- npx -y @burtthecoder/mcp-shodan
  47. # Gemini CLI
  48. gemini mcp add -e SHODAN_API_KEY=your-key shodan npx -y @burtthecoder/mcp-shodan
  49. ```
  50. For Claude Desktop, VS Code and running from source, see [Connect a client](docs/clients.md).
  51. Then ask your agent: *"What is exposed on 8.8.8.8, and is CVE-2021-44228 in the KEV catalog?"* More prompts are in [example workflows](docs/examples.md).
  52. ## Tools
  53. Eleven read-only tools. Full parameters are in the [tool reference](docs/tools.md).
  54. | Group | Tool | What it does |
  55. |---|---|---|
  56. | Network | `ip_lookup` | Ports, products, CVEs, TLS, location and cloud for one IP, optionally with banner history |
  57. | | `shodan_search` | Search devices with Shodan query syntax, with paging and facet breakdowns |
  58. | | `shodan_count` | Total matches and facet breakdowns for a query, without results (free) |
  59. | | `domain_info` | Subdomains and DNS records for a domain |
  60. | | `dns_lookup` | Resolve hostnames to IPs, in batch |
  61. | | `reverse_dns_lookup` | Hostnames for IPs, in batch |
  62. | Vulnerabilities (CVEDB) | `cve_lookup` | CVSS, EPSS, KEV, references and affected CPEs for one CVE |
  63. | | `cpe_lookup` | CPE 2.3 identifiers for a product name |
  64. | | `cves_by_product` | CVEs for a product or CPE, filterable by KEV and date, sortable by EPSS |
  65. | Helpers | `search_filters` | Valid search filter and facet names |
  66. | | `api_info` | Your plan and remaining query and scan credits |
  67. > [!TIP]
  68. > Credits: filtered `shodan_search` queries cost one query credit (plus one per extra page) and `domain_info` costs one per call. `shodan_count`, `ip_lookup`, `dns_lookup`, `reverse_dns_lookup`, `search_filters`, `api_info` and the CVEDB tools are free.
  69. ## HTTP streaming transport
  70. stdio is the default. Set `MCP_TRANSPORT=httpStream` to run a standalone HTTP service:
  71. ```sh
  72. MCP_TRANSPORT=httpStream MCP_PORT=3000 SHODAN_API_KEY=your-key node build/index.js
  73. ```
  74. ```sh
  75. docker build -t mcp-shodan .
  76. docker run -p 127.0.0.1:3000:3000 -e SHODAN_API_KEY=your-key -e MCP_TRANSPORT=httpStream mcp-shodan
  77. ```
  78. A health check is served at `/health`.
  79. ### Environment variables
  80. | Variable | Default | Description |
  81. |---|---|---|
  82. | `SHODAN_API_KEY` | *(required)* | Your Shodan API key |
  83. | `MCP_TRANSPORT` | `stdio` | `stdio` or `httpStream` |
  84. | `MCP_HOST` | `localhost` | Bind address (`httpStream` only). The Docker image sets `0.0.0.0` |
  85. | `MCP_PORT` | `3000` | HTTP port (`httpStream` only) |
  86. | `MCP_ENDPOINT` | `/mcp` | HTTP endpoint path (`httpStream` only) |
  87. ## Security
  88. > [!WARNING]
  89. > The HTTP transport has **no authentication**. Keep the port on localhost or behind an authenticating reverse proxy, or anyone who can reach it can spend your query credits.
  90. - Tool arguments are validated with zod schemas before any request is built. IPs must be valid IPv4 or IPv6, domains valid hostnames, facets `name[:count]` lists, and CVE IDs must match `CVE-YYYY-NNNN`.
  91. - The API key is read from the environment and sent only to `api.shodan.io`. CVEDB calls carry no key.
  92. - What you look up is sent to Shodan.
  93. Report vulnerabilities privately; see [SECURITY.md](SECURITY.md).
  94. ## Troubleshooting
  95. - **401 / invalid key:** check for spaces or quotes around the key, then restart the client. `curl "https://api.shodan.io/api-info?key=$SHODAN_API_KEY"` shows your plan and credits.
  96. - **403 on `shodan_search`:** search filters need a membership or paid API plan. Run `api_info` to see your plan and credits.
  97. - **429:** Shodan allows about one request per second. Retry after a moment.
  98. More in the [troubleshooting guide](docs/troubleshooting.md).
  99. ## Development
  100. ```sh
  101. git clone https://github.com/w0h1v/mcp-shodan && cd mcp-shodan
  102. npm ci
  103. npm test # build + unit tests, no key or network
  104. npx fastmcp dev build/index.js # try tools interactively (needs SHODAN_API_KEY)
  105. ```
  106. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [changelog](CHANGELOG.md).
  107. ## License
  108. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.