Skip to main content
Glama
flagify-com

Nmap MCP Server

by flagify-com
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Nmap MCP Server

GitHub License Python

基于 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 <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 客户端配置，支持两种鉴权方式：

方式 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

测试内容包括：

  1. URL Token 鉴权方式

  2. HTTP Header Bearer Token 鉴权方式

  3. 无 Token 请求（验证拒绝）

  4. 错误 Token 请求（验证拒绝）

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

可用工具

Nmap MCP Server 提供的工具列表：

Nmap MCP Available Tools

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/ ├── 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.)

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/flagify-com/nmap-mcp-http'

If you have feedback or need assistance with the MCP directory API, please join our Discord server