shodan

Name: shodan
Author: w0h1v

本地服务

github.com/w0h1v安全1822 周前更新

代码仓库

关于 shodan

shodan 是面向 AI Agent 的 MCP 服务，用于通过 Shodan API 和 CVEDB 进行网络侦察与漏洞查询。它以只读工具整合主机、设备、DNS 和漏洞信息，并支持 stdio 与 HTTP streaming 传输。

主要功能

01IP 主机侦察
02Shodan 设备搜索与计数
03CVE 和 CPE 情报查询
04域名及批量 DNS 查询
05查看额度与账户计划
06stdio 和 HTTP streaming 传输

适用场景

01检查 IP 暴露的服务与 TLS 详情
02按查询语法和筛选项搜索设备
03核查 CVE 严重性、EPSS 与 KEV 状态
04查找域名子域名并解析主机名

MCP 相关

向 MCP 客户端提供 11 个只读工具，用于查询 Shodan API 和 CVEDB。支持 stdio 与 HTTP streaming；调用 Shodan API 工具需要 API 密钥。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "w0h1v-shodan": {
      "command": "npx",
      "args": [
        "-y",
        "@burtthecoder/mcp-shodan"
      ],
      "env": {
        "SHODAN_API_KEY": "<SHODAN_API_KEY>"
      }
    }
  }
}

启动命令npx -y @burtthecoder/mcp-shodan

需要配置的环境变量

SHODAN_API_KEY密钥Your Shodan API key

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@burtthecoder/mcp-shodan1.0.34stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

快速入门 · 工具 · HTTP · 安全性 · 故障排除 · 文档

mcp-shodan 是一个 MCP 服务，可让 AI Agent 使用 Shodan API 和 Shodan CVEDB。向 Agent 提供 IP、主机名、搜索查询、产品或 CVE，即可获取分析人员会查看的信息：开放端口和横幅、TLS 证书、DNS，以及带有 EPSS 和 KEV 状态的漏洞严重性。

说明

这是独立项目，与 Shodan 无关。你需要自己的 Shodan API 密钥。

亮点

主机侦察。 查询任意 IPv4 或 IPv6 地址的开放端口、产品和版本、已知 CVE、TLS 证书详情（指纹、JARM、JA3S）、云服务提供商和横幅历史记录。
设备搜索。 支持 Shodan 查询语法、分页和分面统计（国家/地区、组织、端口、漏洞等），另有免费的仅计数模式，可用于估算查询规模。
漏洞情报。 提供包含 CVSS v4/v3/v2、EPSS 和 KEV 的 CVE 详情；还可按产品或 CPE 查询 CVE，并按 EPSS 排序。CVEDB 免费使用，不消耗查询额度。
DNS。 获取域名的子域名和 DNS 记录，并在一次调用中对多个名称或 IP 执行正向和反向查询。
关注额度。 免费工具会标记为免费，api_info 会显示套餐剩余额度。
两种传输方式。 stdio 适用于桌面客户端，HTTP 流式传输适用于共享服务。
经过测试。 单元测试使用模拟的 Shodan API，并在 Node 20、22 和 24 上通过 CI 运行。

工作原理

flowchart LR
    A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-shodan"]
    S -->|"validate input,<br/>HTTPS + API key"| SH["Shodan REST API"]
    S -->|"HTTPS, no key"| C["Shodan CVEDB"]
    SH -->|"JSON"| S
    C -->|"JSON"| S
    S -->|"structured JSON text"| A

快速入门

要求： Node.js 20 或更高版本，以及 Shodan API 密钥。

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

# Codex CLI
codex mcp add shodan --env SHODAN_API_KEY=your-key -- npx -y @burtthecoder/mcp-shodan

# Gemini CLI
gemini mcp add -e SHODAN_API_KEY=your-key shodan npx -y @burtthecoder/mcp-shodan

有关 Claude Desktop、VS Code、Smithery 和从源代码运行的说明，请参阅连接客户端。

然后向 Agent 提问：“8.8.8.8 暴露了什么？CVE-2021-44228 是否在 KEV 目录中？” 更多提示词请参阅示例工作流。

工具

共 11 个只读工具。完整参数请参阅工具参考。

分组	工具	功能
网络	`ip_lookup`	查询单个 IP 的端口、产品、CVE、TLS、位置和云信息，还可选择查看横幅历史记录
	`shodan_search`	使用 Shodan 查询语法搜索设备，支持分页和分面分类
	`shodan_count`	查询匹配总数和分面分类，不返回结果（免费）
	`domain_info`	查询域名的子域名和 DNS 记录
	`dns_lookup`	批量将主机名解析为 IP
	`reverse_dns_lookup`	批量查询 IP 对应的主机名
漏洞（CVEDB）	`cve_lookup`	查询单个 CVE 的 CVSS、EPSS、KEV、参考资料和受影响的 CPE
	`cpe_lookup`	查询产品名称对应的 CPE 2.3 标识符
	`cves_by_product`	查询产品或 CPE 对应的 CVE，可按 KEV 和日期筛选，并按 EPSS 排序
辅助工具	`search_filters`	查询有效的搜索筛选项和分面名称
	`api_info`	查询你的套餐以及剩余的查询和扫描额度

提示

额度：带筛选条件的 shodan_search 查询消耗 1 个查询额度（每增加一页另加 1 个），domain_info 每次调用消耗 1 个。shodan_count、ip_lookup、dns_lookup、reverse_dns_lookup、search_filters、api_info 和 CVEDB 工具均免费。

HTTP 流式传输

默认使用 stdio。设置 MCP_TRANSPORT=httpStream 可运行独立的 HTTP 服务：

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

docker build -t mcp-shodan .
docker run -p 127.0.0.1:3000:3000 -e SHODAN_API_KEY=your-key -e MCP_TRANSPORT=httpStream mcp-shodan

/health 提供健康检查。

环境变量

变量	默认值	描述
`SHODAN_API_KEY`	(必填)	你的 Shodan API 密钥
`MCP_TRANSPORT`	`stdio`	`stdio` 或 `httpStream`
`MCP_HOST`	`localhost`	绑定地址（仅用于 `httpStream`）。Docker 镜像会设置为 `0.0.0.0`
`MCP_PORT`	`3000`	HTTP 端口（仅用于 `httpStream`）
`MCP_ENDPOINT`	`/mcp`	HTTP 端点路径（仅用于 `httpStream`）

安全

警告

HTTP 传输没有身份验证。请将端口限制在 localhost，或置于经过身份验证的反向代理之后，否则任何能够访问它的人都可以消耗你的查询额度。

构建任何请求之前，都会使用 zod 架构验证工具参数。IP 必须是有效的 IPv4 或 IPv6 地址，域名必须是有效的主机名，分面必须是 name[:count] 列表，CVE ID 必须符合 CVE-YYYY-NNNN 格式。
API 密钥从环境中读取，且只会发送至 api.shodan.io。CVEDB 调用不携带密钥。
你查询的内容会发送给 Shodan。

请私下报告漏洞；详见 SECURITY.md。

故障排除

401 / 密钥无效： 检查密钥两侧是否有空格或引号，然后重启客户端。运行 curl "https://api.shodan.io/api-info?key=$SHODAN_API_KEY" 可查看你的套餐和额度。
shodan_search 返回 403： 搜索筛选项需要会员资格或付费 API 套餐。运行 api_info 查看你的套餐和额度。
429： Shodan 每秒大约允许 1 个请求。请稍后重试。

更多内容请参阅故障排除指南。

开发

git clone https://github.com/w0h1v/mcp-shodan && cd mcp-shodan
npm ci
npm test                          # build + unit tests, no key or network
npx fastmcp dev build/index.js    # try tools interactively (needs SHODAN_API_KEY)

请参阅 CONTRIBUTING.md 和更新日志。