Nmap MCP Server

Ein auf dem FastMCP-Framework entwickelter Nmap-Scan-Dienst, der Fernzugriff über das Streamable HTTP-Protokoll bietet und die Integration von MCP-Clients (Model Context Protocol) unterstützt.

Screenshot-Vorschau

Verwendung des Nmap MCP Servers für Port-Scans in DeepSOC:

Related MCP server: Nmap MCP Server

Funktionen

• Schnell-Scan - Scannt die gängigsten Ports (ca. 100) des Ziel-Hosts

• Vollständiger Scan - Scannt alle 65535 Ports, unterstützt die Erkennung von Service-Versionen

• Benutzerdefinierter Scan - Unterstützt beliebige Nmap-Befehlsparameter

• Asynchrone Aufgaben - Langwierige Scans werden automatisch in Hintergrundaufgaben umgewandelt; Ergebnisse können über die Aufgaben-ID abgefragt werden

• Token-Authentifizierung - Unterstützt sowohl URL-Parameter als auch Bearer-Token-Authentifizierung

• Strukturierte Ausgabe - Schnell-/Vollständige Scans liefern strukturierte Daten im JSON-Format

Funktionsweise

┌─────────────┐     HTTP/MCP      ┌─────────────────┐
│  MCP Client │ ◄───────────────► │  Nmap MCP Server │
└─────────────┘                   └────────┬────────┘
                                           │
                                           ▼
                                  ┌─────────────────┐
                                  │   Task Manager  │
                                  │    (SQLite)     │
                                  └────────┬────────┘
                                           │
                                           ▼
                                  ┌─────────────────┐
                                  │     Scanner     │
                                  │  (Nmap + XML)   │
                                  └─────────────────┘

1. Anfrageverarbeitung: Der MCP-Client sendet eine Scan-Anfrage über das Streamable HTTP-Protokoll

2. Aufgabenplanung: Der Server erstellt einen Aufgabeneintrag und speichert diesen in einer SQLite-Datenbank

3. Synchrones Warten: Versucht den Scan innerhalb des konfigurierten Timeouts (standardmäßig 30 Sekunden) abzuschließen

4. Asynchrones Fallback: Wenn der Timeout überschritten wird, wird die Aufgabe im Hintergrund ausgeführt und eine Aufgaben-ID für die spätere Abfrage zurückgegeben

5. Ergebnisanalyse: Nmap gibt Daten im XML-Format aus, der Server analysiert diese und gibt strukturiertes JSON zurück

Installation

Systemanforderungen

• Python 3.10+

• Nmap (muss auf dem System installiert sein)

Installationsschritte

# 克隆项目
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 等配置

Konfiguration

Beispiel für die Konfigurationsdatei 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-Bereitstellung

Das Projekt enthält eine Dockerfile und eine docker-compose.yml, sodass es direkt containerisiert ausgeführt werden kann.

Methode A: Bauen und Ausführen aus dem Quellcode (docker compose)

1) Vorbereiten der Ausführungsdateien

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

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

2) Bauen und Starten

docker compose up -d --build

3) Logs anzeigen

docker compose logs -f nmap-mcp-server

4) Dienst stoppen

docker compose down

Methode B: Direktes Abrufen des GHCR-Images (docker pull + docker run)

Geeignet für Szenarien, in denen der Quellcode nicht heruntergeladen werden soll.

1. Lokales Verzeichnis und Konfigurationsdatei vorbereiten:

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

cat > config.json <<'EOF'
{
  "host": "0.0.0.0",
  "port": 3004,
  "path": "/mcp",
  "token": "replace_with_your_token",
  "sync_timeout": 30,
  "max_concurrent_tasks": 10,
  "db_path": "nmap_tasks.db",
  "nmap_path": "nmap"
}
EOF

touch nmap_tasks.db

2. Image abrufen (bevorzugtes Organisations-Repository):

docker pull ghcr.io/flagify-com/nmap-mcp-http:latest
# fallback:
# docker pull ghcr.io/wzfukui/nmap-mcp-http:latest

3. Container starten:

docker run -d \
  --name nmap-mcp-server \
  -p 3004:3004 \
  -v "$(pwd)/config.json:/app/config.json:ro" \
  -v "$(pwd)/nmap_tasks.db:/app/nmap_tasks.db" \
  --restart always \
  ghcr.io/flagify-com/nmap-mcp-http:latest

4. Logs anzeigen:

docker logs -f nmap-mcp-server

5. Container stoppen und löschen:

docker rm -f nmap-mcp-server

Fehlerbehebung bei Mount-Fehlern

Wenn in den Logs der folgende Fehler auftritt:

IsADirectoryError: [Errno 21] Is a directory: '/app/config.json'

Dies bedeutet normalerweise, dass die config.json auf dem Host-System nicht existiert und Docker automatisch ein Verzeichnis mit demselben Namen erstellt und in den Container gemountet hat.

Führen Sie den folgenden Befehl aus, um dies zu beheben (im Ausführungsverzeichnis des Hosts):

docker rm -f nmap-mcp-server
rm -rf config.json
test -d nmap_tasks.db && rm -rf nmap_tasks.db
cat > config.json <<'EOF'
{
  "host": "0.0.0.0",
  "port": 3004,
  "path": "/mcp",
  "token": "replace_with_your_token",
  "sync_timeout": 30,
  "max_concurrent_tasks": 10,
  "db_path": "nmap_tasks.db",
  "nmap_path": "nmap"
}
EOF
touch nmap_tasks.db

Starten Sie anschließend den Container erneut mit docker run ....

GitHub Actions (Docker Publish)

Das Repository enthält eine .github/workflows/docker-publish.yml mit folgenden Auslösern:

• Push auf main

• Push eines v* Tags (z. B. v1.0.0)

• Manuelle Auslösung über workflow_dispatch

Der Workflow führt automatisch folgende Schritte aus:

1. Anmeldung bei GHCR (ghcr.io)

2. Bauen des Docker-Images

3. Pushen des Images nach ghcr.io/<owner>/<repo>

Beispiel für die Image-Adresse:

# 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-<commit>

# fallback (personal):
ghcr.io/wzfukui/nmap-mcp-http:latest
ghcr.io/wzfukui/nmap-mcp-http:main
ghcr.io/wzfukui/nmap-mcp-http:sha-<commit>

Verwendung

Dienst starten

# 使用默认配置文件 (config.json)
python server.py

# 指定配置文件
python server.py -c /path/to/config.json

# 生成配置模板
python server.py --init

MCP-Client-Konfiguration

Nach dem Start des Dienstes wird die MCP-Client-Konfiguration ausgegeben. Es werden zwei Authentifizierungsmethoden unterstützt:

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

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

Test und Verifizierung

Das Projekt enthält einen Test-Client, mit dem schnell überprüft werden kann, ob der MCP-Server ordnungsgemäß funktioniert.

# 激活虚拟环境
source venv/bin/activate

# 运行测试（需要先启动服务）
python test_client.py <your_token>

# 示例
python test_client.py your_secret_token_here

Die Tests umfassen:

1. URL-Token-Authentifizierung

2. HTTP-Header Bearer-Token-Authentifizierung

3. Anfrage ohne Token (Verifizierung der Ablehnung)

4. Anfrage mit falschem Token (Verifizierung der Ablehnung)

Das Testprogramm ruft automatisch das Schnell-Scan-Tool auf und fragt den Aufgabenstatus ab, um sicherzustellen, dass alle Funktionen einwandfrei laufen.

Verfügbare Tools

Liste der vom Nmap MCP Server bereitgestellten Tools:

quick_scan

Scannt die gängigsten Ports (ca. 100) des Ziel-Hosts.

Parameter:

• target (erforderlich): Ziel-IP, Domain oder CIDR-Format

• timeout (optional): Synchroner Warte-Timeout, 5-300 Sekunden

Beispiel:

{"target": "192.168.1.1"}
{"target": "example.com", "timeout": 60}

full_scan

Scannt alle Ports (1-65535) des Ziel-Hosts, einschließlich Service-Versionserkennung.

Parameter:

• target (erforderlich): Ziel-IP, Domain oder CIDR-Format

• timeout (optional): Synchroner Warte-Timeout, 5-600 Sekunden

Beispiel:

{"target": "10.0.0.1", "timeout": 300}

custom_scan

Führt einen benutzerdefinierten Nmap-Befehl aus.

Parameter:

• command (erforderlich): Nmap-Befehlsparameter (ohne den nmap-Befehl selbst)

• timeout (optional): Synchroner Warte-Timeout, 5-600 Sekunden

Beispiel:

{"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

Fragt den Status einer Scan-Aufgabe ab.

Parameter:

• task_id (erforderlich): Aufgaben-ID (UUID-Format)

Rückgabestatus:

• pending: Wartet auf Ausführung

• running: Scan läuft

• completed: Scan abgeschlossen

• failed: Scan fehlgeschlagen

get_task_result

Ruft das vollständige Ergebnis einer Scan-Aufgabe ab.

Parameter:

• task_id (erforderlich): Aufgaben-ID (UUID-Format)

Beispiel für Rückgabeergebnisse

Synchron abgeschlossen

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

Asynchrone Aufgabe

{
  "status": "pending",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "扫描任务已提交，请使用 get_task_status 或 get_task_result 查询结果"
}

Hinweise

Sicherheit

1. Token-Schutz: Bitte ändern Sie unbedingt das Standard-Token, um unbefugten Zugriff zu verhindern

2. Netzwerkisolierung: Es wird empfohlen, den Dienst in einer vertrauenswürdigen Netzwerkumgebung zu betreiben oder in Verbindung mit einer Firewall zu verwenden

3. Berechtigungskontrolle: Dieser Dienst schränkt die Scan-Ziele nicht ein. Bitte stellen Sie sicher, dass er nur für autorisierte Sicherheitstests verwendet wird

4. Befehlsinjektion: Das Tool custom_scan akzeptiert beliebige Nmap-Parameter; bitte bewerten Sie die Risiken

Leistung

1. Parallelitätsbegrenzung: Standardmäßig sind maximal 10 gleichzeitige Aufgaben möglich; Anfragen darüber hinaus werden abgelehnt

2. Timeout-Einstellungen: Vollständige Scans dauern lange; es wird empfohlen, den asynchronen Aufgabenmodus zu verwenden

3. Ressourcenverbrauch: Weitreichende Scans (z. B. /16-Netzwerke) verbrauchen erhebliche Systemressourcen

Bereitstellungsempfehlungen

1. Containerisierte Bereitstellung: Docker wird für die Bereitstellung empfohlen, um Isolierung und Verwaltung zu erleichtern

2. Log-Überwachung: Es wird empfohlen, eine Protokollsammlung zu konfigurieren, um Scan-Aktivitäten zu überwachen

3. Regelmäßige Bereinigung: Die SQLite-Datenbank wächst kontinuierlich; es wird empfohlen, historische Aufgaben regelmäßig zu bereinigen

Projektstruktur

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

Beitrag

Issues und Pull Requests sind willkommen! Dieses Projekt ist vollständig Open Source und wir freuen uns auf die Beteiligung und Beiträge der Community.

Lizenz

Dieses Projekt steht unter der MIT-Lizenz.

Copyright (c) 2025 Shanghai Wuzhi Intelligent Technology Co., Ltd.