mcp-shodan

你是否曾经需要快速了解一个 IP 地址背后的信息？它开放了哪些端口？运行着什么服务？位于哪个城市？或者，你是否在追踪一个安全漏洞，想了解某个具体产品版本受哪些 CVE 影响？手动进行这些查询不仅繁琐，而且需要记住多个不同的 API。

这就是 mcp-shodan 要解决的问题。它是一个基于模型上下文协议的服务器，通过 Shodan 的网络情报 API，让 AI 模型能够直接执行 IP 情报、设备搜索、DNS 查询和漏洞追踪等安全任务。无论你是安全研究员、网络管理员，还是开发者，都可以通过自然语言让 AI 助手为你完成这些复杂的网络侦查工作。

项目基本信息

一、项目介绍

mcp-shodan 是一个功能全面的 MCP 服务器，它封装了 Shodan 的多个 API 端点。Shodan 常被称为“物联网的搜索引擎”，它扫描并索引了全球几乎所有连接互联网的设备。这个服务器提供了七个核心工具，覆盖了网络情报工作的主要场景：

1. IP 情报查询：获取 IP 地址的详细信息，包括开放端口、服务、地理位置、运营商、SSL 证书等。
2. Shodan 设备搜索：使用 Shodan 的搜索语法，在全球范围内查找特定类型的设备（如摄像头、服务器、工业控制系统）。
3. CVE 漏洞查询：根据 CVE 编号获取详细的漏洞信息，包括 CVSS 评分、EPSS 概率、产品影响范围、已知被利用状态等。
4. DNS 正向查询：将域名解析为 IP 地址。
5. DNS 反向查询：根据 IP 地址查找关联的域名。
6. CPE 产品搜索：根据产品名称搜索通用平台枚举标识符。
7. 按产品查询 CVE：查找影响特定产品或 CPE 的所有漏洞。

二、核心优势

一站式网络情报能力
一个服务器集成了 IP 情报、设备发现、DNS 操作和漏洞追踪四大类能力。你不需要为不同任务寻找不同的 MCP 工具。

深入、结构化的返回数据
每个工具返回的数据都经过精心组织。例如，ip_lookup 会分类返回地理位置、服务列表、云提供商信息等；cve_lookup 会清晰地分隔 CVSS v2/v3 评分、EPSS 概率、KEV 状态等。

通过 FastMCP 构建，健壮且现代
项目已迁移到 FastMCP 框架，拥有自动参数验证、模块化工具文件和更简洁的错误处理。代码结构清晰，易于理解和扩展。

支持多种 MCP 客户端
除了 Claude Desktop，还支持 Claude Code、Codex CLI、Gemini CLI 等。无论你使用哪种 AI 编码助手，都可以集成 Shodan 能力。

丰富的过滤和分页选项
尤其是 cves_by_product 工具，提供了多达 10 个参数，包括按 EPSS 排序、按日期过滤、仅显示 KEV 等，让高级用户能够进行精细的漏洞分析。

三、适用场景

安全威胁响应
当出现一个新的高危漏洞，你想知道它是否影响你使用的某个软件版本。你可以问：“CVE-2021-44228 影响哪些 Apache Log4j 版本？” AI 会从 CVE 数据中提取受影响的产品列表。

攻击面管理
作为网络管理员，你可以在 Claude 中问：“我的公网 IP 1.2.3.4 开放了哪些端口？有没有已知的高危漏洞？” AI 会调用 ip_lookup 并向你报告。

数字取证与蓝队分析
在调查一起安全事件时，分析师可以问：“查询 IP 地址 5.6.7.8 的历史数据，它过去运行过哪些服务？” Shodan 可能保留了历史扫描记录。

漏洞情报监控
你可以创建一个定时任务，让 AI 每周查询“影响 Nginx 的最新 5 个 CVE”，并将结果汇总成报告。

渗透测试与红队
测试人员可以问：“搜索所有暴露在公网上的、默认端口为 3389、位于印度的 Windows RDP 服务。” 当然，请务必遵守法律法规和目标授权。

四、安装教程

安装 mcp-shodan 需要你有一个 Shodan API 密钥。你可以从 Shodan 官网注册免费账户获取，但免费账户的查询额度较低。

第一步：获取 Shodan API 密钥

1. 访问 Shodan 官网 并注册/登录。
2. 进入你的账户页面，找到 API Key。

第二步：通过 Smithery 安装（推荐）

关闭 Claude Desktop，在终端中运行：

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

根据提示，输入你的 API 密钥。安装完成后，重新启动 Claude Desktop。

第三步：手动安装与配置

如果你使用 Claude Code、Codex CLI 或 Gemini CLI，可以分别运行：

# Claude Code
claude mcp add --transport stdio --env SHODAN_API_KEY=你的密钥 shodan -- npx -y @burtthecoder/mcp-shodan

# Codex CLI  
codex mcp add shodan --env SHODAN_API_KEY=你的密钥 -- npx -y @burtthecoder/mcp-shodan

对于 Claude Desktop，编辑配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json；Windows: %AppData%\Claude\claude_desktop_config.json），添加：

{
  "mcpServers": {
    "shodan": {
      "command": "npx",
      "args": ["-y", "@burtthecoder/mcp-shodan"],
      "env": {
        "SHODAN_API_KEY": "你的密钥"
      }
    }
  }
}

保存并重启客户端。

五、使用示例

以下是在配置好服务器后，与 Claude 的自然语言对话示例。

示例1：IP 情报查询

用户输入：帮我查一下 IP 地址 8.8.8.8 的详细信息。

AI 会调用 ip_lookup，返回地理位置（美国，加利福尼亚州）、AS 号（AS15169 Google LLC）、开放端口（53 DNS， 443 HTTPS）以及 SSL 证书等信息。

示例2：Shodan 设备搜索

用户输入：搜索所有运行 Apache Tomcat 的中国服务器，只显示前 5 条。

AI 会调用 shodan_search，参数为 query: "Apache Tomcat country:CN", max_results: 5，返回前 5 个匹配设备的 IP、端口和组织信息。

示例3：CVE 漏洞查询

用户输入：CVE-2024-2875 有多严重？

AI 会调用 cve_lookup，返回 CVSS 3.x 评分（假设为 9.8 严重）、影响版本、是否有已知利用、以及补丁信息摘要。

示例4：按产品查询漏洞

用户输入：列出影响 Redis 的所有已知 CVE，并按 CVSS 评分排序。

AI 可能会组合使用 cpe_lookup 找到 Redis 的 CPE，然后调用 cves_by_product 按 EPSS 或 CVSS 排序。由于 cves_by_product 支持 sort_by_epss，AI 可以轻松完成任务。

示例5：DNS 操作

用户输入：解析一下 github.com 的 IP 地址，并对解析出的 IP 做反向查询。

AI 会先调用 dns_lookup，得到 IP 列表，然后对每个 IP 调用 reverse_dns_lookup。

六、常见问题

问题1：查询返回 401 Unauthorized 错误。

解决方案：这表明 API 密钥无效或缺失。请确认：

1. 你在配置文件中正确设置了 SHODAN_API_KEY 环境变量。
2. 密钥没有过期，且与你的 Shodan 账号匹配。
3. 密钥前后没有多余的空格或引号。

问题2：返回 402 Payment Required 错误。

解决方案：这意味着你的 Shodan 账户已没有查询额度。免费账户每月有限额的查询次数。请登录 Shodan 检查用量，或升级到付费计划。

问题3：cves_by_product 工具查询很慢或没有结果。

解决方案：

1. 确保提供了 product 或 cpe23 参数，且不能同时提供。
2. 产品名称要准确。可以先使用 cpe_lookup 找到准确的 CPE，再传入 cpe23 参数。
3. 该工具默认返回最多 1000 条结果，如果结果超过限制，可以分页查询。

问题4：Shodan 搜索返回的结果不完整。

解决方案：免费 API 账户对其他搜索操作也有一定的限制。另外，某些查询可能返回大量结果，建议使用 max_results 参数限制返回数量（默认是 10）。Shodan API 本身对一次请求返回的最大数量有限制。

问题5：这个服务器可以直接扫描我的内网吗？

解决方案：不能。Shodan 只能扫描公网地址，并且是基于其历史扫描数据库。它不会主动扫描你提供的目标，也无法访问你的内部网络。

七、总结

mcp-shodan 是目前功能最全面、最专业的网络安全类 MCP 服务器之一。它将 Shodan 强大的网络情报能力——从 IP 侦查到漏洞分析——无缝地集成到了 AI 助手的工具库中。

该项目的亮点包括：

• 功能全面：七个工具覆盖了网络情报的核心任务。
• 数据深入：返回信息结构化程度高，包含丰富细节。
• 专业性强：支持 CPE、CVSS v2/v3、EPSS、KEV 等专业安全领域的字段。
• 易于集成：支持 Claude Desktop、Claude Code、Codex CLI、Gemini CLI 等多种客户端。

该项目已经有 124 颗星，版本历史活跃，且已经发布到 MCP 官方注册表。对于安全专业人员、网络管理员或任何需要深入理解互联网资产的开发者来说，这个工具能带来巨大的效率提升。请务必遵守 Shodan 的使用条款以及你所在地区的法律法规，负责任地使用该工具。