Shodan MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Shodan MCP Server look up 8.8.8.8 and tell me what ports and CVEs it exposes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shodan MCP Server
Give MCP clients (Cursor, Claude Desktop, VS Code, Codex, and others) full access to Shodan — host recon, banner search, DNS, CVEs, on-demand scans, and network alerts.
Independent project. Not affiliated with Shodan.
What it does
47 tools covering Shodan REST, InternetDB, CVEDB, and the Exploits API
Resources for account credits, search filters/facets, ports, protocols, and alert triggers
Prompts for host recon, exposure search, domain mapping, and CVE triage
Compact summaries by default so models see ports/products/vulns instead of raw banner dumps
Credit warnings on searches that spend query credits
Scan confirmations (
confirm=true, plusconfirm_large/confirm_internetfor wide targets)stdio for desktop clients, Streamable HTTP for a shared process
InternetDB and CVEDB work without an API key
Use this only against assets you are authorized to assess. Shodan's terms of service apply to every request.
Related MCP server: offsec-mcp
Requirements
Node.js 20 or later
A Shodan API key from account.shodan.io for REST/DNS/scans/alerts/exploits
Install
git clone https://github.com/k3nn3dy-ai/Shodan-MCP.git
cd Shodan-MCP
npm install
npm run buildCopy .env.example and export the key (do not commit it):
export SHODAN_API_KEY=your-keyMCP client config
Point the client at dist/index.js. stdio is the default.
Cursor / Claude Desktop / Claude Code
{
"mcpServers": {
"shodan": {
"command": "node",
"args": ["/absolute/path/to/Shodan-MCP/dist/index.js"],
"env": {
"SHODAN_API_KEY": "your-key"
}
}
}
}Docker
docker build -t shodan-mcp .{
"mcpServers": {
"shodan": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "SHODAN_API_KEY", "shodan-mcp"],
"env": {
"SHODAN_API_KEY": "your-key"
}
}
}
}HTTP transport
node dist/index.js --http --port 48731MCP endpoint: http://127.0.0.1:48731/mcp
Health check: http://127.0.0.1:48731/health
Bind stays on localhost unless you pass --host. There is no built-in auth on HTTP — do not expose it to the internet.
Tools
Free without a key:
Tool | Purpose |
| Fast IP enrichment (ports, CPEs, tags, CVE ids) |
| CVE details (CVSS, EPSS, KEV, CPEs) |
| Search CVEs by product or CPE 2.3 |
| CPE dictionary lookup |
REST (API key):
Tool | Purpose | Credits |
| Host card for an IP | none |
| Banner search | 1 if filters or |
| Match count + facets | none |
| Parse a query | none |
| Catalog | none |
| Subdomains + records | none |
| Forward / reverse DNS | none |
| Egress IP Shodan sees | none |
| Crawler catalogs | none |
| Labs honeypot probability | none |
| Plan, credits, org | none |
| On-demand crawl of IPs/CIDRs | 1 scan credit per IP |
| Scan progress | none |
| Enterprise Internet-wide scan | scan credits |
| Network alerts and triggers | plan-dependent |
| Notifier CRUD | plan-dependent |
| Community saved-query directory | none |
| Bulk data listings | plan-dependent |
| Exploit archive | none |
Host and search tools return a compact summary unless you set summary=false. Scans require confirm=true. CIDRs wider than /24 also need confirm_large=true.
Prompts
recon_host— InternetDB → host lookup → CVE triage for one IPsearch_exposure— tokenize, count/facet, then one search pagedomain_osint— domain DNS then enrich resolved IPsvuln_triage— CVEDB + exploits + optional exposure count
Development
npm test
npm run typecheck
npm run dev # stdio
npm run dev:http # http://127.0.0.1:48731Tests mock the Shodan HTTP APIs. They do not spend credits.
Configuration
Variable | Default | Meaning |
| unset | REST / exploits key |
|
| REST origin |
|
| Per-request timeout |
|
| Truncate oversized JSON |
API keys are query parameters on Shodan's side. This server never prints them: errors redact key=....
License
MIT
Available Tools
47 toolsshodan_alert_add_notifierAttach notifier to alertC
Attach a notifier id to an alert (use 'default' for email).
Inputs: id (required), notifier_id (required).
shodan_alert_createCreate network alertB
Monitor an IP or netblock for new services and vulnerabilities. Body matches the Shodan alert API: { name, filters: { ip: [...] }, expires? }.
Inputs: ip (required), name (required), expires.
shodan_alert_deleteDelete alertBDestructiveIdempotent
Delete a network alert by id.
Inputs: id (required).
shodan_alert_disable_triggerDisable alert triggerCDestructiveIdempotent
Disable a trigger on an alert.
Inputs: id (required), trigger (required).
shodan_alert_enable_triggerEnable alert triggerC
Enable one or more comma-separated triggers on an alert.
Inputs: id (required), triggers (required).
shodan_alert_getGet alertBRead-onlyIdempotent
Get one network alert by id.
Inputs: id (required).
shodan_alert_listList alertsARead-onlyIdempotent
List network alerts on the account.
Inputs: no named parameters.
shodan_alert_remove_notifierDetach notifier from alertCDestructiveIdempotent
Remove a notifier from an alert.
Inputs: id (required), notifier_id (required).
shodan_alert_triggersList alert triggersARead-onlyIdempotent
List trigger types that can be enabled on a network alert.
Inputs: no named parameters.
shodan_alert_updateUpdate alertC
Replace the name/filters on an existing alert.
Inputs: id (required), ip (required), name (required), expires.
shodan_api_infoAPI plan and creditsARead-onlyIdempotent
Show the authenticated plan, query credits remaining, and scan credits remaining.
Inputs: no named parameters.
shodan_countCount search resultsARead-onlyIdempotent
Return how many banners match a query, plus optional facets. Does not spend query credits and does not return hosts. Use this before shodan_search.
Inputs: query (required), facets.
shodan_cpesSearch CPEsBRead-onlyIdempotent
Look up CPE 2.3 identifiers for a product name via CVEDB. Free, no API key.
Inputs: product (required), skip, limit.
shodan_cveCVE lookupARead-onlyIdempotent
Look up a CVE in Shodan CVEDB (free, no API key): CVSS, EPSS, KEV, CPEs, references.
Inputs: cve (required).
shodan_cvesSearch CVEsARead-onlyIdempotent
Search CVEDB by product or CPE 2.3. Optional KEV filter and EPSS sort. Free, no API key. Do not pass product and cpe23 together.
Inputs: skip, count, cpe23, limit, +5 more.
shodan_dataset_filesDataset filesBRead-onlyIdempotent
List files inside a named bulk dataset.
Inputs: dataset (required).
shodan_datasetsList datasetsBRead-onlyIdempotent
List bulk data filesets available to the account.
Inputs: no named parameters.
shodan_dns_domainDomain DNSBRead-onlyIdempotent
Return subdomains and DNS records Shodan knows for a domain.
Inputs: domain (required), page, type, history.
shodan_dns_resolveForward DNSBRead-onlyIdempotent
Resolve hostnames to IPs. Comma-separated list.
Inputs: hostnames (required).
shodan_dns_reverseReverse DNSBRead-onlyIdempotent
Resolve IPs to hostnames. Comma-separated list.
Inputs: ips (required).
shodan_exploit_countCount exploitsBRead-onlyIdempotent
Count matching exploits without returning the full result set.
Inputs: query (required), facets.
shodan_exploitsSearch exploitsBRead-onlyIdempotent
Search the Shodan Exploits archive (requires API key). Query filters include cve, type, platform, port, author.
Inputs: query (required), page, facets.
shodan_honeyscoreHoneypot scoreBRead-onlyIdempotent
Labs honeypot probability for an IP, from 0.0 (not a honeypot) to 1.0.
Inputs: ip (required).
shodan_hostHost lookupARead-onlyIdempotent
Look up an IPv4/IPv6 address in Shodan. Default response is a compact analyst summary (org, ports, products, vulns). Set summary=false for the raw banner record. Host lookups do not spend query credits.
Inputs: ip (required), minify, history, summary, +1 more.
shodan_internetdbInternetDB lookupARead-onlyIdempotent
Free, keyless IP enrichment from internetdb.shodan.io: ports, CPEs, hostnames, tags, and CVE ids. Weekly data, no banners. Accepts a single IP or a comma-separated list (max 25).
Inputs: ip (required).
shodan_my_ipMy public IPARead-onlyIdempotent
Return the public IP address Shodan sees for this client.
Inputs: no named parameters.
shodan_notifier_createCreate notifierB
Create a notifier. Provider-specific fields go in args (e.g. to=email@domain for email).
Inputs: provider (required), args, description.
shodan_notifier_deleteDelete notifierCDestructiveIdempotent
Delete a notifier by id.
Inputs: id (required).
shodan_notifier_getGet notifierCRead-onlyIdempotent
Get one notifier by id.
Inputs: id (required).
shodan_notifier_providersNotifier providersARead-onlyIdempotent
List notifier providers and the arguments they require.
Inputs: no named parameters.
shodan_notifiersList notifiersARead-onlyIdempotent
List notifiers configured on the account.
Inputs: no named parameters.
shodan_orgOrganizationBRead-onlyIdempotent
Return organization membership for the API key, if any.
Inputs: no named parameters.
shodan_portsCrawled portsBRead-onlyIdempotent
List ports Shodan crawlers currently scan.
Inputs: no named parameters.
shodan_profileAccount profileARead-onlyIdempotent
Return the Shodan account profile for the configured API key.
Inputs: no named parameters.
shodan_protocolsScan protocolsARead-onlyIdempotent
List protocols available for on-demand Internet scans.
Inputs: no named parameters.
shodan_query_listSaved query directoryCRead-onlyIdempotent
List shared community search queries.
Inputs: page, sort, order.
shodan_query_searchSearch saved queriesCRead-onlyIdempotent
Search the community query directory.
Inputs: query (required), page.
shodan_query_tagsSaved query tagsBRead-onlyIdempotent
List popular tags on the community query directory.
Inputs: size.
shodan_scanOn-demand scanA
Ask Shodan to crawl IPs or CIDRs. Requires confirm=true. CIDRs wider than /24 also need confirm_large=true. Each IP spends 1 scan credit. Paid plan required.
Inputs: ips (required), confirm (required), confirm_large.
shodan_scan_internetInternet-wide scanB
Enterprise-only: crawl the Internet for one port/protocol. Requires confirm=true and confirm_internet=true.
Inputs: port (required), confirm (required), protocol (required), confirm_internet (required).
shodan_scansList scansARead-onlyIdempotent
List on-demand scans submitted by this account.
Inputs: no named parameters.
shodan_scan_statusScan statusBRead-onlyIdempotent
Get progress for an on-demand scan id.
Inputs: id (required).
shodan_searchSearch ShodanARead-onlyIdempotent
Search Shodan's banner database with website query syntax (e.g. 'apache country:DE'). Uses 1 query credit when the query contains filters or page > 1. Prefer shodan_count to size a query first. Default response is compact match rows.
Inputs: query (required), page, facets, fields, +2 more.
shodan_search_facetsList search facetsARead-onlyIdempotent
List facet names that can summarize search results.
Inputs: no named parameters.
shodan_search_filtersList search filtersBRead-onlyIdempotent
List filter names accepted in Shodan search queries.
Inputs: no named parameters.
shodan_search_tokensParse search queryARead-onlyIdempotent
Break a Shodan query into filters, attributes, and leftover free-text. Useful to verify query syntax before spending credits.
Inputs: query (required).
shodan_servicesService namesBRead-onlyIdempotent
Map of port to named service for Shodan crawlers.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 47 tools
Most tools target distinct Shodan resources and actions, with clear separation between search, count, host lookup, DNS, scans, alerts, notifiers, datasets, CVEDB, and exploits. A few boundaries are softer—shodan_host vs. shodan_internetdb both enrich IPs, and cve/cves/cpes and exploits/exploit_count are closely related—but the descriptions generally clarify intended use.
All tools use a consistent shodan_ prefix with snake_case names and mostly predictable noun or noun_action ordering (e.g., shodan_alert_create, shodan_notifier_delete, shodan_dns_resolve). Plural forms for list endpoints are used consistently enough that the pattern remains easy to follow.
47 tools is very large for an MCP server and creates a heavy selection burden for an agent, even though Shodan's API is broad. The surface spans many subdomains, but the count is well beyond the range where tools are easy to scan and choose among.
Coverage is strong across search, host intelligence, DNS, scanning, alerts with triggers and notifiers, community queries, datasets, CVEDB, and exploits. Minor gaps may exist around streaming or other specialized Shodan APIs, but the major workflows are well covered.
Maintenance
Related MCP Connectors
Enrich, search, assess, and manage threat intelligence through 80+ typed MCP tools.
The main MCP server has 10 tools, including six public, read-only CVE tools, site search and page reading. CVE results include source software/version evidence and available CISA KEV and dated FIRST EPSS data. The separate request_security_test action requires an agent key, consent and authorization. A no-account, read-only CVE-only endpoint is https://excessionlabs.ai/mcp/cve. Docs: https://excessionlabs.ai/cve-intelligence/.
Free, read-only public-source threat intel over MCP. No account or API key.
Free MCP server of security & dev API tools -- supply-chain, CVE, DNS, WHOIS, OFAC, Cosmos SDK.
Related MCP Servers
- FlicenseBqualityCmaintenanceEnables network scanning and reconnaissance tasks like port scanning, OS detection, DNS brute force, and more through MCP interfaces.159-
- AlicenseBqualityCmaintenanceMCP server for offensive-security tooling, enabling AI agents to run reconnaissance, CVE intelligence, JavaScript analysis, HTTP probing, and port scanning against authorized targets.10MIT

@guardbee/security-suiteofficial
AlicenseNot gradedqualityFmaintenanceEnables unified security workflows with secret scanning, dependency CVE auditing, TLS/SSL inspection, and DNS/SPF/DMARC checks through a single MCP server.999 npm1MIT- AlicenseNot gradedqualityCmaintenanceProvides safe network reconnaissance through DNS resolution, TLS inspection, HTTP security header grading, and bounded port scanning over the stateless MCP protocol.MIT