NmapMCP

NmapMCP

生产级 Nmap MCP（Model Context Protocol）服务——不只是简单封装。

大多数 Nmap MCP 服务会把 nmap 的输出直接作为原始文本交给 AI，然后就此了事。NmapMCP 会将 nmap 的 XML 输出解析为结构化 JSON，提供 35 个专用工具，而不是一个通用的 nmap_scan，并加入了运行任意网络扫描的工具真正需要的安全防护措施。

⚠️ 仅供教育用途。 只能扫描你拥有或已获明确授权进行测试的主机和网络。请参阅下文的负责任使用。

---

它为何与众不同

结构化输出，而非原始文本。
nmap 的 XML 输出会被完整解析为简洁的 JSON——包括 OS 指纹、MAC 厂商查询结果、CPE 字符串、每个端口的 NSE 脚本结果、traceroute 跳数、运行时间等——因此 AI 助手可以依据字段进行推理，而不必对大段标准输出使用正则表达式。

35 个专用工具，而非一个通用扫描工具。
无需让 AI 记住正确的 NSE 脚本名称和标志组合，每种用途都有专门设计的工具：ssl_scan、smb_vuln_scan、database_scan、dns_enum、rdp_scan、ftp_scan、ssh_audit 等——每个工具都预先配置了合适的脚本和标志。

扫描历史记录与差异比较。
list_scan_history、get_scan_result 和 diff_scans 让你可以运行扫描，之后再次扫描，并询问“有什么变化？”——工具会生成结构化差异，显示新增、关闭或版本发生变化的端口。大多数 Nmap MCP 服务完全不跟踪历史记录。

内置安全防护措施。

• 标志允许列表——每个 nmap 标志都会在传入 shell 前与显式允许列表进行核对；任何未获允许的内容都无法通过
• 目标验证——使用正则表达式检查输入，并限制输入长度
• 私有范围防护——默认阻止公共 IP；扫描公共 IP 必须显式设置 NMAP_ALLOW_PUBLIC=1
• 并发限制——使用信号量将并行扫描数量限制为 3，避免 AI 意外通过同时运行全端口扫描导致网络过载
• 硬性超时——每次扫描在挂起后 1800s 都会被终止

分两阶段进行网络资产盘点。
network_inventory 会先运行 ping 扫描，然后仅对有响应的主机进行服务检测——比直接对整个 /24 网段运行服务扫描高效得多。

易于阅读的摘要。
get_host_summary 会返回格式化的文本报告（主机名、OS 推测、开放端口、脚本摘要、traceroute），供人直接阅读，而不只是供模型解析。

---

工具参考

类别	工具
常规扫描	nmap_scan、structured_scan、quick_scan、top_ports_scan、full_port_scan、check_single_port
主机发现	ping_sweep、arp_scan、network_inventory
扫描技术	syn_stealth_scan、udp_scan、ipv6_scan
服务 / OS	service_scan、os_detection、aggressive_scan、banner_grab
漏洞	vuln_scan、safe_vuln_scan、smb_vuln_scan
协议审计	ssl_scan、http_enum、dns_enum、smb_enum、ftp_scan、ssh_audit、rdp_scan、database_scan
网络分析	firewall_detection、traceroute_scan
脚本	script_scan（按名称运行任意 NSE 脚本 / 类别）
历史记录与报告	list_scan、list_scan_history、get_scan_result、diff_scans、get_host_summary

连接到 Claude 后的提示词示例：

run a quick_scan on 192.168.1.100
get_host_summary on 192.168.1.1
run a vuln_scan on 192.168.1.50
network_inventory of 192.168.1.0/24
diff_scans between scan_id_a and scan_id_b

---

设置

要求

要求	版本	备注
Python	3.13+
Nmap	7.9+	实际的扫描器二进制文件
uv	最新版	Python 包管理器
Claude Desktop	最新版	或任何兼容 MCP 的客户端

1. 安装 Python 3.13+

从 python.org 下载。在 Windows 上，安装时勾选 “Add Python to PATH”。验证：

python --version

2. 安装 Nmap

从 nmap.org 下载。安装时保持勾选 Npcap（Windows）。验证：

nmap --version

3. 安装 uv

pip install uv

4. 获取项目

git clone https://github.com/<your-username>/NmapMCP.git
cd NmapMCP

5. 指定服务使用的 Nmap 二进制文件

默认情况下，服务会通过 NMAP_PATH 环境变量查找 Nmap（找不到时会回退到 Windows 默认路径）。将其设为你的 nmap 实际路径——在 macOS/Linux 上通常只需设为 nmap 或 /usr/bin/nmap；在 Windows 上需要使用带正斜杠的 8.3 短路径，例如 C:/PROGRA~1/Nmap/nmap.exe（使用 where nmap 查找路径，如果路径中包含空格，则将其转换为短路径）。

请将其设为环境变量，而不要编辑源代码：

export NMAP_PATH=/usr/bin/nmap   # macOS/Linux
set NMAP_PATH=C:/PROGRA~1/Nmap/nmap.exe   # Windows

6. 安装依赖项

uv venv
uv pip install -e .

7. 配置 MCP 客户端

添加到你的 Claude Desktop 配置文件中（Windows 上为 %APPDATA%\Claude\claude_desktop_config.json，macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "NmapMCP": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/NmapMCP", "run", "main.py"]
    }
  }
}

重启 Claude Desktop，并查看工具图标以确认已加载。

Docker

此项目包含用于容器化部署的 Dockerfile；详情请参阅该文件。

---

负责任地使用

本项目仅用于教育和授权测试。Nmap 等网络扫描工具可能被滥用于探测未经授权的系统，这在大多数司法管辖区都属于违法行为。

• 只扫描你拥有或已获得明确书面许可进行测试的主机、网络或服务
• 默认禁用对公网 IP 的扫描（需要设置 NMAP_ALLOW_PUBLIC=1 才能覆盖此限制）——除非你确实需要且已获得授权，否则请保持禁用
• 本仓库的维护者不对滥用行为负责

---

故障排除

“nmap not found”——确认在终端中运行 nmap --version 可以正常工作，并确认 NMAP_PATH 指向正确的二进制文件。

（Windows 上）所有目标都显示“0 hosts up”——通常是 Npcap 权限问题。请改用 quick_scan 或 get_host_summary（基于 TCP 连接，无需管理员权限），而不要使用 ping_sweep/arp_scan；也可以以管理员身份运行终端或 Claude Desktop。

Claude Desktop 中未显示工具图标——验证配置 JSON，确认路径正确且为绝对路径，然后完全退出并重新打开 Claude Desktop。

某些扫描需要提升权限——syn_stealth_scan、udp_scan、arp_scan 和 os_detection 通常需要管理员/root 权限。

---

路线图 / 已知限制

以下是项目目前状况的说明：

• 尚无自动化测试套件
• 单文件架构（main.py）——目前运行良好，但未来拆分为 runner/parser/validator/tools 模块将有助于提升可维护性
• 扫描历史仅保存在内存中，重启后不会保留；目前还没有持久化审计日志
• 没有针对单个目标的速率限制（仅限制了全局并行度）

---

许可证

MIT——参见 LICENSE。