基于 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) │
└─────────────────┘
- 请求处理：MCP Client 通过 Streamable HTTP 协议发送扫描请求
- 任务调度：服务器创建任务记录并存入 SQLite 数据库
- 同步等待：在配置的超时时间内（默认 30 秒）尝试完成扫描
- 异步降级：若超时未完成，任务转入后台执行，返回任务 ID 供后续查询
- 结果解析：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 客户端配置，支持两种鉴权方式：
方式 1：URL Token
{
"mcpServers": {
"nmap-scanner": {
"name": "Nmap Scanner",
"type": "streamableHttp",
"description": "Nmap 端口扫描服务",
"isActive": true,
"baseUrl": "http://127.0.0.1:3004/mcp?token=your_token"
}
}
}方式 2：Bearer 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测试内容包括：
- URL Token 鉴权方式
- HTTP Header Bearer Token 鉴权方式
- 无 Token 请求（验证拒绝）
- 错误 Token 请求（验证拒绝）
测试程序会自动调用快速扫描工具并查询任务状态，确保所有功能正常运行。
Nmap MCP Server 提供的工具列表：
快速扫描目标主机的常用端口（约 100 个）。
参数：
target(必填): 目标 IP、域名或 CIDR 格式timeout(可选): 同步等待超时，5-300 秒
示例：
{"target": "192.168.1.1"}
{"target": "example.com", "timeout": 60}全量扫描目标主机的所有端口（1-65535），包含服务版本检测。
参数：
target(必填): 目标 IP、域名或 CIDR 格式timeout(可选): 同步等待超时，5-600 秒
示例：
{"target": "10.0.0.1", "timeout": 300}执行自定义 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}查询扫描任务状态。
参数：
task_id(必填): 任务 ID（UUID 格式）
返回状态：
pending: 等待执行running: 正在扫描completed: 扫描完成failed: 扫描失败
获取扫描任务的完整结果。
参数：
task_id(必填): 任务 ID（UUID 格式）
{
"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 查询结果"
}- Token 保护：请务必修改默认 Token，避免未授权访问
- 网络隔离：建议在可信网络环境中运行，或配合防火墙使用
- 权限控制：本服务不限制扫描目标，请确保仅用于授权的安全测试
- 命令注入：
custom_scan工具接受任意 Nmap 参数，请评估风险
- 并发限制：默认最多 10 个并发任务，超出时请求会被拒绝
- 超时设置：全量扫描耗时较长，建议使用异步任务模式
- 资源占用：大范围扫描（如 /16 网段）会消耗大量系统资源
- 容器化部署：推荐使用 Docker 部署，便于隔离和管理
- 日志监控：建议配置日志收集，监控扫描活动
- 定期清理：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.)