Nmap MCP HTTP

Nmap MCP Server

](https://github.com/flagify-com/nmap-mcp-http)   ](../../actions/workflows/docker-publish.yml)

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

截图预览

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

DeepSOC with Nmap MCP

功能特性

• 快速扫描 - 扫描目标主机的常用端口（约 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 
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"
}

Docker 部署

项目已提供 Dockerfile 与 docker-compose.yml，可直接容器化运行。

方式 A：基于源码构建运行（docker compose）

1) 准备运行文件

# 初始化配置文件（请修改 token）
cp config.example.json config.json

# 预创建 SQLite 文件，避免被 Docker 识别成目录
touch nmap_tasks.db

2) 构建并启动

docker compose up -d --build

3) 查看日志

docker compose logs -f nmap-mcp-server

4) 停止服务

docker compose down

方式 B：直接拉取 GHCR 镜像运行（docker pull + docker run）

适用于不想拉源码、只想直接运行容器的场景。

1) 准备本地目录和配置文件：

mkdir -p nmap-mcp-data
cd nmap-mcp-data

cat > config.json  config.json /`

示例镜像地址：

preferred (org):

ghcr.io/flagify-com/nmap-mcp-http:latest ghcr.io/flagify-com/nmap-mcp-http:main ghcr.io/flagify-com/nmap-mcp-http:sha-

fallback (personal):

ghcr.io/wzfukui/nmap-mcp-http:latest ghcr.io/wzfukui/nmap-mcp-http:main ghcr.io/wzfukui/nmap-mcp-http:sha-

## 使用方法

### 启动服务

使用默认配置文件 (config.json)

python server.py

指定配置文件

python server.py -c /path/to/config.json

生成配置模板

python server.py --init

### MCP 客户端配置

服务启动后会打印 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

示例

python test_client.py your_secret_token_here

**测试内容包括：**
1. URL Token 鉴权方式
2. HTTP Header Bearer Token 鉴权方式
3. 无 Token 请求（验证拒绝）
4. 错误 Token 请求（验证拒绝）

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

## 可用工具

**Nmap MCP Server 提供的工具列表：**

![Nmap MCP Available Tools](images/nmap-mcp-available-tools.png)

### 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` (必填): 任务 ID（UUID 格式）

**返回状态：**
- `pending`: 等待执行
- `running`: 正在扫描
- `completed`: 扫描完成
- `failed`: 扫描失败

### get_task_result

获取扫描任务的完整结果。

**参数：**
- `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 查询结果" }

## 注意事项

### 安全相关

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

### 性能相关

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

### 部署建议

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

## 项目结构

nmap-mcp-http/ ├── .github/workflows/ │ └── docker-publish.yml # GitHub Actions Docker 构建与发布 ├── .dockerignore # Docker 构建忽略规则 ├── Dockerfile # 容器镜像构建文件 ├── 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 依赖 ├── docker-compose.yml # 本地容器编排 ├── VERSION # 版本号 ├── LICENSE # MIT 开源许可证 ├── README.md # 项目说明 └── images/ # 截图资源 ├── deepsoc-with-nmap-mcp.png └── nmap-mcp-available-tools.png

## 贡献

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

## 许可证

本项目采用 [MIT License](LICENSE) 开源许可证。

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