Nmap MCP Server

Сервис сканирования Nmap, разработанный на базе фреймворка FastMCP, предоставляющий возможности удаленного вызова через протокол Streamable HTTP и поддерживающий интеграцию с клиентами MCP (Model Context Protocol).

Предварительный просмотр

Использование Nmap MCP Server для сканирования портов в DeepSOC:

Related MCP server: Nmap MCP Server

Функциональные особенности

• Быстрое сканирование - сканирование наиболее часто используемых портов целевого хоста (около 100).

• Полное сканирование - сканирование всех 65535 портов с поддержкой определения версий сервисов.

• Пользовательское сканирование - поддержка любых параметров команд Nmap.

• Асинхронные задачи - длительное сканирование автоматически переводится в фоновый режим, результаты можно получить по ID задачи.

• Аутентификация по токену - поддержка двух способов аутентификации: через параметры URL и Bearer Token.

• Структурированный вывод - быстрое/полное сканирование возвращает структурированные данные в формате JSON.

Принцип работы

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

1. Обработка запроса: MCP-клиент отправляет запрос на сканирование через протокол 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"
}

Развертывание в Docker

Проект включает Dockerfile и docker-compose.yml для запуска в контейнере.

Способ А: Сборка и запуск из исходного кода (docker compose)

1) Подготовка файлов для запуска

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

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

2) Сборка и запуск

docker compose up -d --build

3) Просмотр логов

docker compose logs -f nmap-mcp-server

4) Остановка сервиса

docker compose down

Способ Б: Запуск через образ GHCR (docker pull + docker run)

Подходит для случаев, когда вы не хотите скачивать исходный код, а хотите сразу запустить контейнер.

1. Подготовьте локальную директорию и файл конфигурации:

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. Скачайте образ:

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

3. Запустите контейнер:

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. Просмотрите логи:

docker logs -f nmap-mcp-server

5. Остановите и удалите контейнер:

docker rm -f nmap-mcp-server

Устранение распространенных ошибок монтирования

Если в логах появляется следующая ошибка:

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

Обычно это означает, что файл config.json на хосте отсутствует, и Docker автоматически создал директорию с таким же именем и смонтировал ее в контейнер.

Выполните следующую команду для исправления (в рабочей директории на хосте):

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

Затем снова выполните docker run ... для запуска контейнера.

GitHub Actions (Docker Publish)

В репозиторий добавлен файл .github/workflows/docker-publish.yml, условия запуска:

• push в ветку main

• push тега v* (например, v1.0.0)

• ручной запуск workflow_dispatch

Workflow автоматически выполняет:

1. Вход в GHCR (ghcr.io)

2. Сборку Docker-образа

3. Пуш образа в ghcr.io/<owner>/<repo>

Пример адреса образа:

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

Использование

Запуск сервиса

# 使用默认配置文件 (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. Запрос без токена (проверка отказа)

4. Запрос с неверным токеном (проверка отказа)

Тестовая программа автоматически вызывает инструмент быстрого сканирования и запрашивает статус задачи, чтобы убедиться в корректной работе всех функций.

Доступные инструменты

Список инструментов, предоставляемых Nmap MCP Server:

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. Защита токена: Обязательно измените токен по умолчанию, чтобы избежать несанкционированного доступа.

2. Сетевая изоляция: Рекомендуется запускать в доверенной сетевой среде или использовать совместно с межсетевым экраном.

3. Контроль доступа: Сервис не ограничивает цели сканирования, пожалуйста, используйте его только для авторизованного тестирования безопасности.

4. Инъекции команд: Инструмент custom_scan принимает любые параметры Nmap, оцените риски.

Производительность

1. Ограничение параллелизма: По умолчанию максимум 10 параллельных задач, запросы сверх этого лимита будут отклонены.

2. Настройка тайм-аута: Полное сканирование занимает много времени, рекомендуется использовать режим асинхронных задач.

3. Потребление ресурсов: Масштабное сканирование (например, подсети /16) потребляет значительные системные ресурсы.

Рекомендации по развертыванию

1. Контейнеризация: Рекомендуется использовать Docker для изоляции и управления.

2. Мониторинг логов: Рекомендуется настроить сбор логов для мониторинга активности сканирования.

3. Регулярная очистка: База данных SQLite будет постоянно расти, рекомендуется периодически очищать историю задач.

Структура проекта

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

Вклад в проект

Приветствуются Issue и Pull Request! Проект полностью открыт, мы ждем участия сообщества.

Лицензия

Проект распространяется под лицензией MIT License.

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