Nmap MCP Server

基于 FastMCP 框架开发的 Nmap 扫描服务通过 Streamable HTTP 协议提供远程调用能力支持 MCP (Model Context Protocol) 客户端集成

截图预览

在 DeepSOC 中使用 Nmap MCP Server 进行端口扫描

功能特性

• 快速扫描 - 扫描目标主机的常用端口约 100 个
• 全量扫描 - 扫描全部 65535 个端口支持服务版本检测
• 自定义扫描 - 支持任意 Nmap 命令参数
• 异步任务 - 长时间扫描自动转为后台任务通过任务 ID 查询结果
• Token 鉴权 - 支持 URL 参数和 Bearer Token 两种认证方式
• 结构化输出 - 快速/全量扫描返回 JSON 格式的结构化数据

工作机制

     HTTP/MCP      
  MCP Client     Nmap MCP Server 
                   
                                           
                                           
                                  
                                     Task Manager  
                                      (SQLite)     
                                  
                                           
                                           
                                  
                                       Scanner     
                                    (Nmap + XML)   
                                  

1. 请求处理MCP Client 通过 Streamable HTTP 协议发送扫描请求
2. 任务调度服务器创建任务记录并存入 SQLite 数据库
3. 同步等待在配置的超时时间内默认 30 秒尝试完成扫描
4. 异步降级若超时未完成任务转入后台执行返回任务 ID 供后续查询
5. 结果解析Nmap 以 XML 格式输出服务器解析后返回结构化 JSON

安装

环境要求

• Python 3.10+
• Nmap系统需已安装

安装步骤

# 克隆项目
git clone <repository-url>
cd nmap-mcp-http

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 生成配置文件模板
python server.py --init

# 编辑配置文件
cp config.example.json config.json
vim config.json  # 修改 token 等配置

配置

配置文件 config.json 示例

{
  "host": "0.0.0.0",
  "port": 3004,
  "path": "/mcp",
  "token": "your_secret_token_here",
  "sync_timeout": 30,
  "max_concurrent_tasks": 10,
  "db_path": "nmap_tasks.db",
  "nmap_path": "nmap"
}

参数	说明	默认值
host	监听地址	0.0.0.0
port	监听端口	3004
path	MCP 服务路径	/mcp
token	鉴权令牌	自动生成
sync_timeout	同步等待超时秒	30
max_concurrent_tasks	最大并发任务数	10
db_path	SQLite 数据库路径	nmap_tasks.db
nmap_path	Nmap 可执行文件路径	nmap

使用方法

启动服务

# 使用默认配置文件 (config.json)
python server.py

# 指定配置文件
python server.py -c /path/to/config.json

# 生成配置模板
python server.py --init

MCP 客户端配置

服务启动后会打印 MCP 客户端配置支持两种鉴权方式

方式 1URL Token

{
  "mcpServers": {
    "nmap-scanner": {
      "name": "Nmap Scanner",
      "type": "streamableHttp",
      "description": "Nmap 端口扫描服务",
      "isActive": true,
      "baseUrl": "http://127.0.0.1:3004/mcp?token=your_token"
    }
  }
}

方式 2Bearer Token

{
  "mcpServers": {
    "nmap-scanner": {
      "name": "Nmap Scanner",
      "type": "streamableHttp",
      "description": "Nmap 端口扫描服务",
      "isActive": true,
      "baseUrl": "http://127.0.0.1:3004/mcp",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}

测试验证

项目自带测试客户端程序可快速验证 MCP Server 是否正常工作

# 激活虚拟环境
source venv/bin/activate

# 运行测试需要先启动服务
python test_client.py <your_token>

# 示例
python test_client.py your_secret_token_here

测试内容包括

1. URL Token 鉴权方式
2. HTTP Header Bearer Token 鉴权方式
3. 无 Token 请求验证拒绝
4. 错误 Token 请求验证拒绝

测试程序会自动调用快速扫描工具并查询任务状态确保所有功能正常运行

可用工具

Nmap MCP Server 提供的工具列表

quick_scan

快速扫描目标主机的常用端口约 100 个

参数

• target (必填): 目标 IP域名或 CIDR 格式
• timeout (可选): 同步等待超时5-300 秒

示例

{"target": "192.168.1.1"}
{"target": "example.com", "timeout": 60}

full_scan

全量扫描目标主机的所有端口1-65535包含服务版本检测

参数

• target (必填): 目标 IP域名或 CIDR 格式
• timeout (可选): 同步等待超时5-600 秒

示例

{"target": "10.0.0.1", "timeout": 300}

custom_scan

执行自定义 Nmap 命令

参数

• command (必填): Nmap 命令参数不含 nmap 命令本身
• timeout (可选): 同步等待超时5-600 秒

示例

{"command": "-sS -p 80,443,8080 192.168.1.1"}
{"command": "-sV -sC -p 22 example.com"}
{"command": "--script vuln 192.168.1.1", "timeout": 120}

get_task_status

查询扫描任务状态

参数

• task_id (必填): 任务 IDUUID 格式

返回状态

• pending: 等待执行
• running: 正在扫描
• completed: 扫描完成
• failed: 扫描失败

get_task_result

获取扫描任务的完整结果

参数

• task_id (必填): 任务 IDUUID 格式

返回结果示例

同步完成

{
  "status": "completed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "target": "192.168.1.1",
    "scan_time": 2.5,
    "hosts": [
      {
        "address": "192.168.1.1",
        "status": "up",
        "ports": [
          {
            "port": 22,
            "protocol": "tcp",
            "state": "open",
            "service": "ssh",
            "version": "OpenSSH 8.0"
          },
          {
            "port": 80,
            "protocol": "tcp",
            "state": "open",
            "service": "http",
            "version": "nginx 1.18.0"
          }
        ]
      }
    ]
  }
}

异步任务

{
  "status": "pending",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "扫描任务已提交请使用 get_task_status 或 get_task_result 查询结果"
}

注意事项

安全相关

1. Token 保护请务必修改默认 Token避免未授权访问
2. 网络隔离建议在可信网络环境中运行或配合防火墙使用
3. 权限控制本服务不限制扫描目标请确保仅用于授权的安全测试
4. 命令注入custom_scan 工具接受任意 Nmap 参数请评估风险

性能相关

1. 并发限制默认最多 10 个并发任务超出时请求会被拒绝
2. 超时设置全量扫描耗时较长建议使用异步任务模式
3. 资源占用大范围扫描如 /16 网段会消耗大量系统资源

部署建议

1. 容器化部署推荐使用 Docker 部署便于隔离和管理
2. 日志监控建议配置日志收集监控扫描活动
3. 定期清理SQLite 数据库会持续增长建议定期清理历史任务

项目结构

nmap-mcp-http/
 server.py          # MCP 服务器主程序
 config.py          # 配置管理模块
 models.py          # 数据模型定义
 scanner.py         # Nmap 扫描器封装
 task_manager.py    # 任务管理器SQLite
 auth.py            # Token 鉴权中间件
 test_client.py     # 测试客户端
 config.json        # 配置文件需自行创建
 config.example.json # 配置文件模板
 requirements.txt   # Python 依赖
 VERSION            # 版本号
 LICENSE            # MIT 开源许可证
 README.md          # 项目说明
 images/            # 截图资源
     deepsoc-with-nmap-mcp.png
     nmap-mcp-available-tools.png

贡献

欢迎提交 Issue 和 Pull Request本项目完全开源期待社区的参与和贡献

许可证

本项目采用 MIT License 开源许可证

Copyright (c) 2025 上海雾帜智能科技有限公司 (Shanghai Wuzhi Intelligent Technology Co., Ltd.)