AI导哈

Nmap扫描服务器

一个提供Nmap扫描功能的MCP服务器，支持多种扫描类型和脚本搜索，适用于网络安全分析和AI助手集成。

  • by joswr1ght
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 joswr1ght/nmap-mcp

使用说明

Nmap MCP服务器

一种模型上下文协议（MCP）服务器，为AI助手和其他MCP客户端提供Nmap扫描功能。

特性

  • TCP连接端口扫描：对指定目标执行TCP连接扫描
  • 版本检测：使用 -sV 检测服务版本
  • 脚本扫描：使用以下命令运行Nmap脚本 -sC 或自定义脚本
  • 脚本搜索：按名称、类别或关键字搜索可用的Nmap脚本
  • 多种扫描类型：支持TCP连接、SYN和UDP扫描
  • 灵活端口规格：支持端口范围、列表、前N个端口和所有端口
  • 定时控制：可配置的定时模板（T0-T5）
  • 多个目标：在单个操作中扫描多个主机或IP范围
  • 扫描历史记录：扫描结果的持久存储和检索
  • SSE支持：基于web的MCP客户端的服务器发送事件
  • JSON输出：结构化JSON响应，便于解析

需求

  • Python 3.10+
  • Nmap安装在系统上
  • uv包管理器（推荐）

安装

使用紫外线（推荐）

# Clone the repository
git clone <repository-url>
cd nmap-mcp

# Run directly with uv (will install dependencies automatically)
uv run nmap_mcp.py

使用pip

# Install dependencies
pip install mcp asyncio-sse python-nmap

# Run the server
python nmap_mcp.py

使用Docker

# Build the container
docker build -t nmap-mcp .

# Run in SSE mode for web clients
docker run -p 3001:3001 nmap-mcp

# Run in stdio mode (for direct MCP client connection)
docker run -i nmap-mcp uv run nmap_mcp.py

用法

命令行选项

python nmap_mcp.py [options]

Options:
  -d, --daemon        Run in daemon mode (only available with --sse)
  --sse              Enable SSE mode for web clients
  --port PORT        Port for SSE server (default: 3001)
  --host HOST        Host for SSE server (default: localhost)

可用工具

1. tcp_scan

对一个或多个目标执行TCP端口扫描。

参数：

  • targets （必填）：IP地址、主机名或CIDR范围列表
  • ports （必填）：端口规格（例如，“80443”、“1-1000”、“全部”、“前1000”）
  • scan_type：扫描类型（“连接”、“syn”、“udp”）-默认值：“连接”
  • timing：Nmap定时模板（“T0”到“T5”）-默认值：“T3”
  • skip_ping：跳过主机发现（布尔值）-默认值：false
  • verbose：启用详细输出（布尔值）-默认值：false

例子：

{
  "targets": ["192.168.1.1", "google.com"],
  "ports": "top-1000",
  "scan_type": "syn",
  "timing": "T4"
}

2. version_scan

对指定端口执行版本检测扫描。

参数：

  • targets （必填）：要扫描的目标列表
  • ports （必填）：端口规格
  • timing：定时模板-默认值：“T3”
  • skip_ping：跳过主机发现-默认值：false
  • verbose：启用详细输出-默认值：false

例子：

{
  "targets": ["192.168.1.1"],
  "ports": "22,80,443",
  "timing": "T3"
}

3. script_scan

使用默认或自定义脚本执行Nmap脚本扫描。

参数：

  • targets （必填）：要扫描的目标列表
  • ports （必填）：端口规格
  • scripts （必需）：脚本规范（-sC的“默认”或特定脚本名称）
  • timing：定时模板-默认值：“T3”
  • skip_ping：跳过主机发现-默认值：false
  • verbose：启用详细输出-默认值：false

例子：

{
  "targets": ["192.168.1.1"],
  "ports": "80,443",
  "scripts": "http-enum,http-headers"
}

4. search_scripts

按名称、类别或关键字搜索可用的Nmap脚本。

参数：

  • query （必填）：搜索脚本名称、类别或关键字
  • category：按脚本类别筛选（可选）

例子：

{
  "query": "http",
  "category": "discovery"
}

5. get_scan_history

使用可选筛选检索扫描历史记录。

参数：

  • limit：要返回的最大扫描次数-默认值：10
  • target_filter：按目标筛选扫描（部分匹配）

例子：

{
  "limit": 5,
  "target_filter": "192.168.1"
}

扫描历史记录

扫描结果会自动存储在内存中，并可以持久保存到 scan_history.json 当服务器正常关闭时。历史包括：

  • 扫描ID和时间戳
  • 扫描类型和参数
  • 已执行完整的Nmap命令
  • 原始和解析输出
  • 执行时间和状态

发展

运行测试

# Install development dependencies
uv sync --extra dev

# Run tests
uv run pytest

代码格式化

# Format code
uv run black nmap_mcp.py
uv run isort nmap_mcp.py

# Type checking
uv run mypy nmap_mcp.py

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

故障排除

“Nmap在此系统上不可用”

确保Nmap已安装并可在PATH中访问：

# On Ubuntu/Debian
sudo apt-get install nmap

# On macOS
brew install nmap

# On Red Hat/CentOS
sudo yum install nmap

权限问题

某些Nmap扫描类型（如SYN扫描）需要root权限：

# Run with sudo if needed
sudo uv run nmap_mcp.py

港口准入问题

如果在SSE模式下运行并且无法访问web界面：

  1. 检查端口（默认3001）是否未被防火墙阻止
  2. 确保主机绑定正确（外部访问使用“0.0.0.0”）
  3. 验证没有其他服务正在使用同一端口

Claude桌面配置

要在Claude Desktop中使用nmap mcp服务器，您需要将其添加到mcp配置文件中。

步骤1：查找配置文件

Claude Desktop配置文件位于：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%\Claude\claude_desktop_config.json

步骤2：添加服务器配置

编辑配置文件以包含nmap mcp服务器：

{
  "mcpServers": {
    "nmap-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/nmap-mcp",
        "nmap_mcp.py"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/path/to/nmap-mcp/.venv"
      }
    }
  }
}

重要：替换 /path/to/nmap-mcp 使用nmap-mcp安装目录的实际路径。

步骤3：替代配置（Python）

如果你更喜欢直接使用Python而不是uv：

{
  "mcpServers": {
    "nmap-mcp": {
      "command": "python",
      "args": [
        "/path/to/nmap-mcp/nmap_mcp.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/nmap-mcp"
      }
    }
  }
}

步骤4:重新启动克劳德桌面

保存配置文件后，重新启动Claude Desktop以使更改生效。

步骤5：验证连接

一旦Claude Desktop重新启动，您应该能够在对话中使用nmap扫描功能。您可以通过要求Claude进行测试：

  • “扫描scanme.nmap.org上的前100个端口”
  • “搜索与HTTP相关的Nmap脚本”
  • “显示扫描历史记录”

配置示例

用于开发（本地安装）

{
  "mcpServers": {
    "nmap-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/username/Dev/nmap-mcp",
        "nmap_mcp.py"
      ]
    }
  }
}

用于系统安装

{
  "mcpServers": {
    "nmap-mcp": {
      "command": "nmap-mcp",
      "args": []
    }
  }
}

使用自定义定时（更快的扫描）

{
  "mcpServers": {
    "nmap-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/nmap-mcp",
        "nmap_mcp.py"
      ],
      "env": {
        "NMAP_DEFAULT_TIMING": "T4"
      }
    }
  }
}

克劳德桌面集成故障排除

找不到服务器

  • 验证nmap mcp目录的路径是否正确
  • 确保uv已安装并可在PATH中访问
  • 检查nmap_mcp.py是否具有执行权限

权限不足

  • 确保Claude Desktop有权执行服务器
  • 对于SYN扫描，您可能需要以提升的权限运行Claude Desktop
  • 考虑使用不需要root访问权限的TCP连接扫描

连接超时

  • 检查Nmap是否已安装且可访问
  • 验证目标扫描的网络连接
  • 尝试手动运行服务器以测试功能：
    cd /path/to/nmap-mcp
uv run nmap_mcp.py

配置验证

您可以通过检查Claude Desktop日志或独立测试服务器来验证您的配置：

# Test server startup
cd /path/to/nmap-mcp
python test_setup.py

# Test MCP communication
python example_client.py

相关 MCP