Servidor MCP de Nmap

Servicio de escaneo Nmap desarrollado sobre el framework FastMCP, que proporciona capacidades de invocación remota a través del protocolo Streamable HTTP y admite la integración con clientes MCP (Model Context Protocol).

Vista previa de capturas de pantalla

Uso del Servidor MCP de Nmap en DeepSOC para escaneo de puertos:

Related MCP server: Nmap MCP Server

Características

• Escaneo rápido - Escanea los puertos comunes (aprox. 100) del host objetivo

• Escaneo completo - Escanea los 65535 puertos, con soporte para detección de versiones de servicio

• Escaneo personalizado - Admite parámetros de comandos Nmap arbitrarios

• Tareas asíncronas - Los escaneos de larga duración se convierten automáticamente en tareas en segundo plano, permitiendo consultar resultados mediante un ID de tarea

• Autenticación por Token - Admite métodos de autenticación mediante parámetros de URL y Bearer Token

• Salida estructurada - Los escaneos rápidos/completos devuelven datos estructurados en formato JSON

Mecanismo de funcionamiento

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

1. Procesamiento de solicitudes: El cliente MCP envía una solicitud de escaneo a través del protocolo Streamable HTTP

2. Programación de tareas: El servidor crea un registro de tarea y lo almacena en una base de datos SQLite

3. Espera síncrona: Intenta completar el escaneo dentro del tiempo de espera configurado (30 segundos por defecto)

4. Degradación asíncrona: Si no se completa a tiempo, la tarea pasa a ejecutarse en segundo plano y devuelve un ID de tarea para consultas posteriores

5. Análisis de resultados: Nmap genera una salida en formato XML, que el servidor analiza y devuelve como JSON estructurado

Instalación

Requisitos del entorno

• Python 3.10+

• Nmap (debe estar instalado en el sistema)

Pasos de instalación

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

Configuración

Ejemplo del archivo de configuración 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"
}

Despliegue con Docker

El proyecto incluye Dockerfile y docker-compose.yml, lo que permite ejecutarlo directamente en contenedores.

Método A: Construcción y ejecución desde el código fuente (docker compose)

1) Preparar los archivos de ejecución

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

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

2) Construir e iniciar

docker compose up -d --build

3) Ver registros

docker compose logs -f nmap-mcp-server

4) Detener el servicio

docker compose down

Método B: Ejecución directa mediante imagen de GHCR (docker pull + docker run)

Ideal para escenarios donde no se desea descargar el código fuente y solo se quiere ejecutar el contenedor.

1. Preparar el directorio local y el archivo de configuración:

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. Descargar la imagen (priorizando el repositorio de la organización):

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

3. Iniciar el contenedor:

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. Ver registros:

docker logs -f nmap-mcp-server

5. Detener y eliminar el contenedor:

docker rm -f nmap-mcp-server

Solución de problemas de montaje

Si los registros muestran el siguiente error:

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

Generalmente significa que el archivo config.json no existe en el host, y Docker creó automáticamente un directorio con el mismo nombre y lo montó en el contenedor.

Ejecute el siguiente comando para corregirlo (en el directorio de ejecución del host):

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

Luego, vuelva a ejecutar docker run ... para iniciar el contenedor.

GitHub Actions (Docker Publish)

El repositorio incluye .github/workflows/docker-publish.yml, con los siguientes disparadores:

• push a main

• push de etiquetas v* (ej. v1.0.0)

• Disparo manual workflow_dispatch

El flujo de trabajo realizará automáticamente:

1. Inicio de sesión en GHCR (ghcr.io)

2. Construcción de la imagen Docker

3. Envío de la imagen a ghcr.io/<owner>/<repo>

Ejemplo de dirección de imagen:

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

Modo de uso

Iniciar el servicio

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

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

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

Configuración del cliente MCP

Tras iniciar el servicio, se mostrará la configuración del cliente MCP, que admite dos métodos de autenticación:

Método 1: Token en URL

{
  "mcpServers": {
    "nmap-scanner": {
      "name": "Nmap Scanner",
      "type": "streamableHttp",
      "description": "Nmap 端口扫描服务",
      "isActive": true,
      "baseUrl": "http://127.0.0.1:3004/mcp?token=your_token"
    }
  }
}

Método 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"
      }
    }
  }
}

Verificación de pruebas

El proyecto incluye un programa cliente de prueba para verificar rápidamente si el servidor MCP funciona correctamente.

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

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

# 示例
python test_client.py your_secret_token_here

Las pruebas incluyen:

1. Método de autenticación por Token en URL

2. Método de autenticación por Bearer Token en cabecera HTTP

3. Solicitud sin Token (verificación de rechazo)

4. Solicitud con Token incorrecto (verificación de rechazo)

El programa de prueba llamará automáticamente a la herramienta de escaneo rápido y consultará el estado de la tarea para asegurar que todas las funciones operen correctamente.

Herramientas disponibles

Lista de herramientas proporcionadas por el Servidor MCP de Nmap:

quick_scan

Escaneo rápido de los puertos comunes (aprox. 100) del host objetivo.

Parámetros:

• target (obligatorio): IP, dominio o formato CIDR del objetivo

• timeout (opcional): Tiempo de espera síncrono, de 5 a 300 segundos

Ejemplo:

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

full_scan

Escaneo completo de todos los puertos del host objetivo (1-65535), incluyendo detección de versiones de servicio.

Parámetros:

• target (obligatorio): IP, dominio o formato CIDR del objetivo

• timeout (opcional): Tiempo de espera síncrono, de 5 a 600 segundos

Ejemplo:

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

custom_scan

Ejecuta un comando Nmap personalizado.

Parámetros:

• command (obligatorio): Parámetros del comando Nmap (sin incluir el comando nmap en sí)

• timeout (opcional): Tiempo de espera síncrono, de 5 a 600 segundos

Ejemplo:

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

Consulta el estado de una tarea de escaneo.

Parámetros:

• task_id (obligatorio): ID de la tarea (formato UUID)

Estados de retorno:

• pending: Esperando ejecución

• running: Escaneando

• completed: Escaneo completado

• failed: Escaneo fallido

get_task_result

Obtiene el resultado completo de una tarea de escaneo.

Parámetros:

• task_id (obligatorio): ID de la tarea (formato UUID)

Ejemplo de resultados

Completado de forma síncrona

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

Tarea asíncrona

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

Notas importantes

Seguridad

1. Protección de Token: Asegúrese de cambiar el Token por defecto para evitar accesos no autorizados

2. Aislamiento de red: Se recomienda ejecutar en entornos de red confiables o utilizar cortafuegos

3. Control de permisos: Este servicio no limita los objetivos de escaneo; asegúrese de usarlo solo para pruebas de seguridad autorizadas

4. Inyección de comandos: La herramienta custom_scan acepta parámetros Nmap arbitrarios; evalúe los riesgos

Rendimiento

1. Límite de concurrencia: Por defecto, admite un máximo de 10 tareas concurrentes; las solicitudes adicionales serán rechazadas

2. Configuración de tiempo de espera: Los escaneos completos consumen mucho tiempo; se recomienda usar el modo de tareas asíncronas

3. Consumo de recursos: Los escaneos a gran escala (ej. segmento /16) consumen muchos recursos del sistema

Recomendaciones de despliegue

1. Despliegue en contenedores: Se recomienda usar Docker para facilitar el aislamiento y la gestión

2. Monitoreo de registros: Se recomienda configurar la recolección de registros para monitorear las actividades de escaneo

3. Limpieza periódica: La base de datos SQLite crecerá continuamente; se recomienda limpiar las tareas antiguas periódicamente

Estructura del proyecto

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

Contribuciones

¡Las propuestas de Issues y Pull Requests son bienvenidas! Este proyecto es totalmente de código abierto y esperamos la participación y contribución de la comunidad.

Licencia

Este proyecto se publica bajo la Licencia MIT.

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