Nmap Mcp Server

安全 Python

🚀 Nmap MCP 服务器

Nmap MCP 服务器是一个模型上下文协议（MCP）服务器，它使用 FastMCP 和标准输入输出（stdio）传输方式，将 Nmap 命令行工具的功能以 MCP 工具的形式暴露出来。该服务器通过 Nmap 命令行工具提供了全面的网络扫描能力。

🚀 快速开始

FastMCP 实现

本服务器基于 FastMCP 构建，这是一个现代、高性能的 MCP 框架，具备以下特点：

简化的 API：基于装饰器的简洁工具注册方式
类型安全：完整的类型提示和验证
标准输入输出传输：通过标准输入输出实现高效通信
异步支持：支持非阻塞操作并具备完善的错误处理机制

✨ 主要特性

Nmap MCP 服务器使用 FastMCP 装饰器暴露了以下工具：

1. 基础扫描 (`nmap_basic_scan`)

可执行不同强度级别的基础 Nmap 扫描：

快速扫描：高吞吐量的快速扫描
全面扫描：包含服务检测和操作系统检测的完整扫描
隐身扫描：低特征扫描，避免被检测

2. 服务检测 (`nmap_service_detection`)

检测目标主机上运行的服务和版本，强度级别可配置（0 - 9）。

3. 操作系统检测 (`nmap_os_detection`)

检测目标主机上运行的操作系统，重试次数可配置。

4. 脚本扫描 (`nmap_script_scan`)

运行 NSE（Nmap 脚本引擎）脚本，用于高级侦察和漏洞评估。

5. 隐身扫描 (`nmap_stealth_scan`)

使用可配置的计时模板执行 SYN 扫描，尽量减少被检测的风险。

6. 全面扫描 (`nmap_comprehensive_scan`)

结合多种检测方法执行全功能扫描。

7. ping 扫描 (`nmap_ping_scan`)

使用各种 ping 方法（ICMP、TCP 或两者结合）发现存活主机。

8. 端口扫描 (`nmap_port_scan`)

使用不同方法（SYN、Connect、UDP）扫描特定端口。

9. 漏洞扫描 (`nmap_vulnerability_scan`)

运行不同类别的漏洞检测脚本。

10. 网络发现 (`nmap_network_discovery`)

发现整个网络中的主机和服务。

11. 自定义扫描 (`nmap_custom_scan`)

使用用户定义的 Nmap 选项进行扫描，提供最大的灵活性。

📦 安装指南

前提条件

Python 3.10 或更高版本
系统 PATH 中已安装并可访问 Nmap

安装 Nmap

macOS：

brew install nmap

Ubuntu/Debian：

sudo apt update
sudo apt install nmap

CentOS/RHEL：

sudo yum install nmap
# 或对于较新版本：
sudo dnf install nmap

Windows： 从 nmap.org 下载并安装。

安装步骤

克隆本仓库：

git clone 
cd nmap-mcp-server

安装依赖：

pip install -e .

💻 使用示例

运行 FastMCP 服务器

可直接使用标准输入输出传输方式运行服务器：

python server.py

或者使用已安装的脚本：

nmap-mcp-server

Claude Desktop 配置

在 Claude Desktop MCP 设置中添加以下配置：

{
"mcpServers": {
"NmapMCP": {
"command": "uv",
"args": [
"--directory",
"/Users/haji/mcp-servers/nmap-mcp-server",
"run",
"server.py"
]
}
}
}

配置步骤：

打开 Claude Desktop
转到设置 → MCP 服务器
添加上述 JSON 配置
重启 Claude Desktop
验证服务器是否已连接

基础用法

基础网络扫描

# 该工具调用时使用了类型化参数
result = await nmap_basic_scan(
targets="192.168.1.0/24",
ports="common",
scan_type="quick"
)

服务检测

result = await nmap_service_detection(
targets="example.com",
ports="80,443,8080",
intensity=7
)

漏洞评估

result = await nmap_vulnerability_scan(
targets="192.168.1.100",
ports="common",
vuln_category="all"
)

自定义扫描

result = await nmap_custom_scan(
targets="example.com",
custom_options="-sS -p 1-1000 -A --script=vuln",
output_format="normal"
)

高级用法

FastMCP 架构

服务器使用了 FastMCP 的简洁装饰器模式：

@app.tool(
name="nmap_basic_scan",
description="Perform a basic Nmap scan of specified targets"
)
async def nmap_basic_scan(
targets: str,
ports: str = "common",
scan_type: str = "quick"
) -> str:
"""Perform a basic Nmap scan of specified targets."""
# 此处为实现代码
return result

📚 详细文档

安全注意事项

⚠️ 重要安全提示

法律合规：仅扫描您拥有或获得明确授权的网络和系统。

网络影响：某些扫描可能会占用大量资源，影响网络性能。

检测风险：激进的扫描可能触发安全系统和防火墙。

速率限制：服务器包含超时和速率限制，以防止滥用。

错误处理

FastMCP 服务器包含全面的错误处理机制，用于处理以下情况：

Nmap 命令未找到
命令超时
参数无效
网络连接问题
权限错误

日志记录

服务器使用 Python 内置的日志系统，日志包括：

命令执行细节
错误消息
性能指标

测试

测试 FastMCP 服务器：

# 测试工具注册和功能
python test_fastmcp.py

# 测试示例
python example_usage.py

贡献代码

分叉仓库
创建功能分支
进行修改
如有必要，添加测试
提交拉取请求

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

免责声明

本工具仅用于教育和授权的安全测试目的。用户在扫描任何网络或系统之前，有责任确保获得了适当的授权。

支持

遇到问题或有疑问时：

检查错误日志
验证 Nmap 是否已安装并可访问
确保您拥有适当的权限
在仓库中创建一个问题

变更日志

版本 1.0.0

首次发布，实现 FastMCP
支持所有主要的 Nmap 扫描技术
全面的错误处理
标准输入输出传输模式
类型安全的工具定义
使用 uv 进行 Claude Desktop 配置

0 条评论
分类：安全