OPNsense MCP Server

Защищённый Model Context Protocol (MCP) сервер для управления межсетевыми экранами OPNsense через ИИ-ассистентов, таких как Claude Code, Cursor и другие инструменты, совместимые с MCP.

81 инструмент в 10 областях: система, межсетевой экран, сеть, DNS, DHCP, VPN, HAProxy, службы, диагностика и безопасность.

Требования

• Python 3.11+

• OPNsense 24.7 или новее — MCP-сервер использует API-эндпоинты на основе MVC, появившиеся в OPNsense 24.7. В более старых версиях используется другая структура API, которая несовместима. Сервер автоматически определяет версию OPNsense при первом подключении и выбирает правильное именование эндпоинтов (camelCase для версий до 25.7, snake_case для 25.7+). OPNsense 26.x полностью поддерживается, включая изменённый формат ответа о состоянии прошивки.

Related MCP server: OPNsense MCP Server

Модель безопасности

Этот MCP-сервер разработан с безопасностью как главным приоритетом:

• Только чтение по умолчанию — операции записи требуют явного согласия через OPNSENSE_ALLOW_WRITES=true

• Сохранение точки/откат (только OPNsense < 26.7) — там, где OPNsense всё ещё предлагает API сохранения точки, изменения межсетевого экрана используют встроенный 60-секундный автоматический откат; изменения должны быть явно подтверждены, иначе они откатываются автоматически. OPNsense 26.7 удалил этот API выше по течению — сервер обнаруживает отсутствующий эндпоинт во время выполнения и применяет изменения межсетевого экрана немедленно, без автоматического отката

• Блок-лист эндпоинтов — опасные эндпоинты (halt, reboot, poweroff, firmware update/upgrade) жёстко заблокированы на уровне API-клиента и никогда не могут быть вызваны

• Только API — нет доступа по SSH, нет выполнения команд, нет прямого манипулирования файлами конфигурации

• Локальный транспорт — только STDIO, нет сетевых HTTP/SSE-эндпоинтов

• Отсутствие раскрытия учётных данных — ключи API никогда не включаются в вывод инструментов, журналы или сообщения об ошибках

• Проверка ввода — параметры имени хоста проверяются на внедрение метасимволов оболочки

• Удаление конфиденциальных данных — резервная копия конфигурации по умолчанию удаляет пароли и ключи

Быстрый старт

1. Создание ключа API OPNsense

1. Войдите в веб-интерфейс OPNsense

2. Перейдите в System > Access > Users

3. Отредактируйте существующего пользователя или создайте выделенного пользователя API:

   • Для производственного использования создайте выделенного пользователя (например, mcp-api) только с необходимыми привилегиями

   • Для доступа только для чтения назначьте пользователя в группу с доступом к API только для чтения

4. Прокрутите вниз до раздела API keys и нажмите кнопку +

5. Будет сгенерирована пара ключ/секрет и загружен файл (apikey.txt)

6. Файл содержит две строки — key=your-api-key-here и secret=your-api-secret-here

7. Храните эти учётные данные в безопасности — секрет нельзя будет получить из OPNsense повторно

Совет: Для настройки только для чтения (рекомендуется для начала работы) вам не нужно менять какие-либо разрешения — доступа к API по умолчанию достаточно для всех инструментов только для чтения.

2. Установка

# Using pip
pip install opnsense-mcp-server

# Using uv (recommended for isolated environments)
uv pip install opnsense-mcp-server

# Using Docker
docker pull uhlenheide/opnsense-mcp-server

# From source
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e .

Образ Docker: официальный образ — uhlenheide/opnsense-mcp-server, публикуемый из этого репозитория через .github/workflows/publish-docker.yml при каждом теге v*. Образа lucamarien/opnsense-mcp-server не существует — в более ранних версиях README он был указан по ошибке.

3. Настройка вашего ИИ-ассистента

Claude Code

Добавьте в файл .mcp.json вашего проекта:

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false",
        "OPNSENSE_ALLOW_WRITES": "false"
      }
    }
  }
}

Альтернатива: Используйте "command": "python", "args": ["-m", "opnsense_mcp"], если CLI opnsense-mcp отсутствует в вашем PATH.

Или добавьте глобально в ~/.claude/claude_code_config.json.

Claude Code (Docker)

{
  "mcpServers": {
    "opnsense": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPNSENSE_URL=https://192.168.1.1/api",
        "-e", "OPNSENSE_API_KEY=your-api-key-here",
        "-e", "OPNSENSE_API_SECRET=your-api-secret-here",
        "-e", "OPNSENSE_VERIFY_SSL=false",
        "-e", "OPNSENSE_ALLOW_WRITES=false",
        "uhlenheide/opnsense-mcp-server"
      ]
    }
  }
}

Cursor

Добавьте в настройки MCP в Cursor (Settings > MCP):

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Конфигурация

Нестандартные порты: Если веб-интерфейс OPNsense работает на нестандартном порту (например, 10443), укажите его в URL: https://192.168.1.1:10443/api

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

Система (7 инструментов)

Сеть (5 инструментов)

Межсетевой экран (21 инструмент)

Примечание: Защита с помощью точки сохранения существует только на OPNsense < 26.7. На 26.7+ эти инструменты применяют изменения немедленно и постоянно — см. Операции записи и точки сохранения.

DNS (13 инструментов)

DHCP (8 инструментов)

VPN (3 инструмента)

HAProxy (8)

Полное управление конфигурацией балансировщика нагрузки HAProxy (требуется плагин os-haproxy).

Примечание: изменения HAProxy НЕ используют защиту savepoint — они применяются немедленно при реконфигурации. Всегда вызывайте opn_haproxy_configtest перед opn_reconfigure_haproxy.

Службы (11)

Диагностика (4)

Безопасность (1)

Операции записи и savepoint

Операции записи требуют OPNSENSE_ALLOW_WRITES=true. На OPNsense < 26.7 изменения брандмауэра дополнительно проходят через механизм savepoint OPNsense:

1. Перед любым изменением брандмауэра автоматически создаётся savepoint

2. Изменение применяется (переключение правила, добавление или удаление)

3. Начинается 60-секундный обратный отсчёт — если не подтвердить, OPNsense автоматически откатывает изменение

4. Используйте opn_confirm_changes с возвращённым revision, чтобы сделать изменения постоянными

На этих версиях, если ИИ-ассистент сделает плохое изменение брандмауэра, которое заблокирует вас, изменение автоматически откатится в течение 60 секунд.

OPNsense 26.7 удалил API savepoint/rollback выше по течению, поэтому на 26.7+ автоматического отката нет. Сервер не жёстко задаёт версию: он проверяет наличие конечной точки savepoint при первой записи в брандмауэр, и если OPNsense отвечает, что конечная точка не существует, переходит к прямому применению на остаток сессии. Проверьте opn_mcp_info — его поле savepoint_support сообщает true, false или null, если запись ещё не проверялась. Инструменты записи затем возвращают пустой revision, opn_confirm_changes отвечает status: "not_applicable", и каждое изменение брандмауэра немедленно и постоянно.

Предупреждение: На OPNsense 26.7+ сделайте резервную копию конфигурации (opn_download_config или System > Configuration > Backups) перед включением записи и сохраните внешний доступ к устройству — правило, которое заблокирует вас, не откатится само.

Примечание: opn_reconfigure_unbound, opn_reconfigure_haproxy, opn_reconfigure_ddclient, opn_reconfigure_dnsmasq и opn_configure_mdns_repeater требуют записи, но не используют savepoints — они применяют изменения конфигурации служб и не подлежат автоматическому откату.

Поддержка IPv6

Полностью автоматизировано через MCP

• Правила межсетевого экрана IPv6 — создание правил с ip_protocol="inet6" (защищено механизмом savepoint на OPNsense < 26.7)

• Привязки HAProxy IPv6 — фронтенды с адресами привязки [::]:443 или [2001:db8::1]:443

• Бэкенды HAProxy IPv6 — серверы с IPv6-адресами, resolvePrefer: ipv6 на бэкендах

• Динамический DNS с IPv6 — DDNS-аккаунты с методами checkip, поддерживающими IPv6

• Диапазоны DHCPv6 (dnsmasq) — IPv6-диапазоны DHCP с настройкой Router Advertisement

• DNS-записи AAAA — переопределения хостов Unbound с IPv6-адресами

• Диагностика IPv6 — Traceroute с ip_version="6", ping по имени хоста

Требует ручной настройки через GUI

Эти параметры не поддерживаются через MVC API в OPNsense и должны настраиваться через веб-GUI:

• Настройка IPv6 на WAN — PPPoE с делегированием префикса DHCPv6, статический IPv6, SLAAC

• Настройка адресации IPv6 на LAN — режим Track Interface, статическое назначение /64, идентификатор префикса

• Назначение интерфейсов — назначение физических портов на роли WAN/LAN/OPT

• Туннели 6to4/6rd — механизмы переходных туннелей

Известные ограничения

• ISC DHCP / Kea DHCPv6: не реализовано. Для диапазонов DHCPv6 и Router Advertisement поддерживается только dnsmasq (современный вариант по умолчанию). ISC DHCP устарел; видимость аренд Kea DHCPv6 в API ограничена.

• radvd: не реализован как отдельный набор инструментов. Dnsmasq обрабатывает Router Advertisement нативно через конфигурацию диапазонов. На каждом интерфейсе должен работать только один демон RA.

• Правила межсетевого экрана dual-stack: inet46 (dual-stack) корректно работает в правилах MVC API (opn_add_firewall_rule). Однако inet46 в устаревших XML-правилах фильтра (GUI) молча не даёт результата в PF — это известная ошибка OPNsense, которая затрагивает только устаревшие правила.

• Устаревшие правила GUI: правила межсетевого экрана, созданные через традиционный GUI OPNsense, недоступны через MVC API. Для доступа только на чтение используйте opn_get_config_section("filter").

Рекомендуемый порядок миграции на IPv6

1. Вручную (GUI): Настройте IPv6 на WAN (DHCPv6-PD от провайдера или статический)

2. Вручную (GUI): Настройте интерфейсы LAN (режим Track Interface для делегирования префикса)

3. MCP: Настройте Router Advertisement через opn_add_dnsmasq_range с флагами RA

4. MCP: Создайте правила межсетевого экрана IPv6 (ICMPv6 должен быть разрешён для NDP/RA/PMTUD)

5. MCP: Добавьте DNS-записи IPv6 через opn_add_dns_override

6. MCP: Настройте Dynamic DNS с методом checkip для IPv6

7. MCP: Добавьте IPv6-адреса привязки во фронтенды HAProxy

8. MCP: Проверьте с помощью opn_ping, opn_traceroute (ip_version="6"), opn_gateway_status

Совместимость версий

При первом подключении сервер автоматически определяет версию OPNsense и выбирает правильное соглашение об именовании эндпоинтов API (camelCase для версий до 25.7, snake_case для 25.7+).

Примечание о правилах межсетевого экрана: opn_list_firewall_rules показывает правила, управляемые через MVC/automation API. Правила, настроенные через GUI OPNsense, используют устаревший формат, недоступный через этот API. Это известное ограничение OPNsense.

Устранение неполадок

Проблемы с подключением

"Connection refused" или ошибки тайм-аута

• Убедитесь, что OPNSENSE_URL заканчивается на /api (например, https://192.168.1.1/api)

• Если используется нестандартный порт, укажите его: https://192.168.1.1:10443/api

• Убедитесь, что веб-GUI OPNsense доступен с машины, на которой запущен MCP-сервер

Ошибки SSL-сертификата

• Для самоподписанных сертификатов (стандартная настройка OPNsense) установите OPNSENSE_VERIFY_SSL=false

• Для продакшена установите корректный сертификат на OPNsense и оставьте OPNSENSE_VERIFY_SSL=true

Проблемы аутентификации

401 Unauthorized

• Проверьте, что OPNSENSE_API_KEY и OPNSENSE_API_SECRET указаны верно

• Ключи API чувствительны к регистру — скопируйте их точно из загруженного apikey.txt

• Проверьте, что пользователь API не отключён в OPNsense

• Убедитесь, что у пользователя API достаточно прав для операций, которые вы пытаетесь выполнить

403 Forbidden

• Возможно, у пользователя API недостаточно разрешений для запрошенного эндпоинта

• Для операций записи убедитесь, что установлено OPNSENSE_ALLOW_WRITES=true

Проблемы конкретных инструментов

opn_list_firewall_rules возвращает пустые результаты

• Этот инструмент показывает только правила MVC/automation, а не устаревшие правила GUI

• Чтобы увидеть их, создавайте правила через automation API или opn_add_firewall_rule

opn_ping завершается по тайм-ауту

• Возможно, у межсетевого экрана нет маршрута до целевого хоста

• Проверьте статус шлюза с помощью opn_gateway_status

• Тайм-аут по умолчанию — 30 секунд (30 циклов опроса)

opn_download_config показывает значения [REDACTED]

• Это поведение по умолчанию для обеспечения безопасности. Передайте include_sensitive=true, чтобы включить пароли и ключи (используйте с осторожностью в диалогах с ИИ)

Операции записи завершаются ошибкой "writes not enabled"

• Установите OPNSENSE_ALLOW_WRITES=true в конфигурации вашего MCP-сервера

• По соображениям безопасности эта возможность намеренно отключена по умолчанию

Не удаётся подтвердить savepoint

• Параметр revision должен точно совпадать со значением, возвращённым операцией записи

• Подтверждение должно быть выполнено в течение 60 секунд, иначе изменение будет автоматически отменено

• На OPNsense 26.7+ API savepoint отсутствует: инструменты записи возвращают пустой revision, а opn_confirm_changes возвращает status: "not_applicable". Это ожидаемое поведение, а не ошибка — изменение уже применено окончательно

Диагностические команды

Если вам нужно отладить MCP-сервер:

# Test API connectivity directly
curl -k -u "your-key:your-secret" https://your-opnsense-ip/api/core/firmware/status

# Run the server directly
python -m opnsense_mcp

# Run tests to verify installation
pytest -v

Разработка

# Clone and install dev dependencies
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e ".[dev]"

# Run all tests (no real OPNsense needed — all tests use mocked API)
pytest -v

# Full CI pipeline (lint, format, type check, security scan, tests)
make validate

# Individual checks
ruff check src/ tests/          # Lint (includes bandit security checks)
ruff format src/ tests/          # Format
mypy src/ --strict               # Type checking

Лучшие практики

Тематические руководства по типовым задачам настройки межсетевого экрана:

• WhatsApp Calling Firewall Rules — разрешение голосовых и видеозвонков WhatsApp через межсетевой экран с политикой default-deny с помощью URL-алиасов таблиц и ограниченных правил

Эти руководства демонстрируют реальные примеры использования инструментов MCP и объясняют соображения безопасности, стоящие за каждым подходом.

Участие в разработке

Подробные рекомендации см. в CONTRIBUTING.md. Ключевые моменты:

1. Все тесты должны использовать имитированные ответы API — никогда не подключайтесь к реальному OPNsense

2. Инструменты не должны дублировать друг друга — каждый инструмент должен иметь своё уникальное назначение

3. Пишите понятные docstring — это единственный ориентир ИИ при выборе инструмента

4. Возвращайте структурированные данные (словари), а не форматированные строки

5. Запустите make validate перед отправкой

Лицензия

MIT