Nmap MCP Server

🚀 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 下载并安装。

安装步骤

1. 克隆本仓库：

git clone <repository-url>
cd nmap-mcp-server

2. 安装依赖：

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"
      ]
    }
  }
}

配置步骤：

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

基础用法

基础网络扫描

# 该工具调用时使用了类型化参数
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

📚 详细文档

安全注意事项

⚠️ 重要安全提示

1. 法律合规：仅扫描您拥有或获得明确授权的网络和系统。
2. 网络影响：某些扫描可能会占用大量资源，影响网络性能。
3. 检测风险：激进的扫描可能触发安全系统和防火墙。
4. 速率限制：服务器包含超时和速率限制，以防止滥用。

错误处理

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

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

日志记录

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

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

测试

测试 FastMCP 服务器：

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

# 测试示例
python example_usage.py

贡献代码

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

许可证

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

免责声明

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

支持

遇到问题或有疑问时：

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

变更日志

版本 1.0.0

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