Skip to main content
Glama
deenesjakoruzh
lucamarien

OPNsense MCP Server

by lucamarien
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

OPNsense MCP Server

Claude Code、Cursor、その他のMCP互換ツールなどのAIアシスタントを通じてOPNsenseファイアウォールを管理するための、安全なModel Context Protocol（MCP）サーバー。

システム、ファイアウォール、ネットワーク、DNS、DHCP、VPN、HAProxy、サービス、診断、セキュリティの10ドメインにわたる81のツール。

要件

  • Python 3.11以上

  • OPNsense 24.7以降 — MCPサーバーはOPNsense 24.7で導入されたMVCベースのAPIエンドポイントに依存しています。それより古いバージョンは互換性のない異なるAPI構造を使用しています。サーバーは初回接続時にOPNsenseのバージョンを自動検出し、正しいエンドポイント命名（25.7以前はcamelCase、25.7以降はsnake_case）を選択します。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. OPNsense APIキーを作成する

  1. OPNsenseのWebインターフェースにログインします

  2. System > Access > Usersに移動します

  3. 既存のユーザーを編集するか、専用のAPIユーザーを作成します：

    • 本番環境では、必要な権限のみを持つ専用ユーザー（例：mcp-api）を作成します

    • 読み取り専用アクセスの場合は、読み取り専用APIアクセスを持つグループにユーザーを割り当てます

  4. API keysセクションまでスクロールし、**+**ボタンをクリックします

  5. キー/シークレットのペアが生成され、ファイル（apikey.txt）がダウンロードされます

  6. ファイルには2行が含まれています — 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. AIアシスタントを設定する

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

代替： opnsense-mcp CLIがPATHにない場合は、"command": "python", "args": ["-m", "opnsense_mcp"]を使用します。

または、~/.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

CursorのMCP設定（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_URL

（必須）

OPNsense APIベースURL（/apiで終わる必要があります）

OPNSENSE_API_KEY

（必須）

OPNsenseユーザー設定からのAPIキー

OPNSENSE_API_SECRET

（必須）

OPNsenseユーザー設定からのAPIシークレット

OPNSENSE_VERIFY_SSL

true

SSL証明書を検証（自己署名証明書の場合はfalse）

OPNSENSE_ALLOW_WRITES

false

書き込み操作を有効化（ファイアウォールルール、サービス制御）

カスタムポート： OPNsenseのWeb GUIが標準以外のポート（例：10443）で実行されている場合は、URLに含めます：https://192.168.1.1:10443/api

利用可能なツール（81）

システム（7ツール）

ツール

説明

opn_system_status

ファームウェアバージョン、製品名、アーキテクチャを含むシステム情報

opn_list_services

すべてのサービスとその実行状態を一覧表示します。パラメータ：search、limit

opn_gateway_status

ゲートウェイの可用性、遅延、dpingerヘルスチェック

opn_download_config

config.xmlバックアップをダウンロードし、機密データの除去をオプションで指定できます。パラメータ：include_sensitive（デフォルト：false — パスワードとキーは編集されます）

opn_scan_config

完全な設定をスキャンし、セクションに解析し、ランタイムインベントリ（ファームウェア、プラグイン、DHCP、DNS、インターフェース、サービス）を収集します。結果はセッションごとにキャッシュされます。パラメータ：force

opn_get_config_section

特定の設定セクションを構造化JSONとして取得します。パラメータ：section、include_sensitive

opn_mcp_info

MCPサーバーバージョン、書き込みモードの状態、検出されたOPNsenseバージョン、APIスタイル、ファイアウォールの書き込みがまだセーブポイント/ロールバック保護を受けているかどうか

ネットワーク（5ツール）

ツール

説明

opn_interface_stats

インターフェースごとのトラフィック統計（送受信バイト数、パケット、エラー）

opn_arp_table

IPからMACアドレスへのマッピングを示すARPテーブル

opn_ndp_table

IPv6からMACアドレスへのマッピングを示すNDP（Neighbor Discovery Protocol）テーブル

opn_ipv6_status

全インターフェースのIPv6設定とアドレス状態（メソッド、ライブアドレス、サマリー）

opn_list_static_routes

設定された静的ルート。パラメータ：search、limit

ファイアウォール（21ツール）

ツール

説明

書き込み

opn_list_firewall_rules

MVCファイアウォールフィルタールールを一覧表示します。パラメータ: search, limit

なし

opn_list_firewall_aliases

エイリアス定義（IPリスト、ポートグループ、GeoIP、URL）を一覧表示します。パラメータ: search, limit

なし

opn_list_nat_rules

NATポートフォワーディング（DNAT）ルールを一覧表示します。パラメータ: search, limit

なし

opn_list_firewall_categories

ファイアウォールルールカテゴリとそのUUIDを一覧表示します。パラメータ: search, limit

なし

opn_firewall_log

クライアント側フィルタリング付きの最近のファイアウォールログエントリ。パラメータ: source_ip, destination_ip, action, interface, limit

なし

opn_confirm_changes

保留中の変更を確認し、60秒の自動ロールバックをキャンセルします（OPNsense < 26.7。26.7+ではnot_applicableを返すno-op）。パラメータ: revision

あり

opn_toggle_firewall_rule

セーブポイント付きでルールの有効/無効状態を切り替えます（OPNsense < 26.7）。パラメータ: uuid

あり

opn_add_firewall_rule

セーブポイント付きで新しいフィルタールールを作成します（OPNsense < 26.7）。パラメータ: action, direction, interface, ip_protocol, protocol, source_net, destination_net, destination_port, description

あり

opn_delete_firewall_rule

UUIDでフィルタールールをセーブポイント付きで削除します（OPNsense < 26.7）。パラメータ: uuid

あり

opn_add_alias

新しいエイリアスを作成します。パラメータ: name, alias_type, content, description

あり

opn_add_nat_rule

セーブポイント付きでNATポートフォワーディングルールを作成します（OPNsense < 26.7）。パラメータ: destination_port, target_ip, interface, protocol, target_port, description

あり

opn_add_firewall_category

新しいファイアウォールルールカテゴリを作成します。パラメータ: name, color

あり

opn_delete_firewall_category

UUIDでファイアウォールルールカテゴリをセーブポイント付きで削除します（OPNsense < 26.7）。パラメータ: uuid

あり

opn_set_rule_categories

セーブポイント付きでファイアウォールルールにカテゴリを割り当てます（OPNsense < 26.7）。パラメータ: uuid, categories

あり

opn_add_icmpv6_rules

RFC 4890に基づいてIPv6運用に必要な必須のICMPv6ルール（NDP、RA、ping6）を作成します。パラメータ: interface

あり

opn_update_alias

既存のエイリアス（名前、内容、タイプ、説明）を更新します。読み取り・変更・書き込み。パラメータ: uuid, name, content, description, alias_type, enabled

あり

opn_delete_alias

UUIDでエイリアスを削除します。まずルール参照を確認します。パラメータ: uuid

あり

opn_toggle_alias

エイリアスの有効/無効状態を切り替えます。パラメータ: uuid

あり

opn_update_firewall_rule

セーブポイント付きでフィルタールールフィールドを更新します（OPNsense < 26.7）。パラメータ: uuid, action, direction, interface, ip_protocol, protocol, source_net, source_not, source_port, destination_net, destination_not, destination_port, gateway, log, quick, sequence, categories, description, enabled

あり

opn_update_nat_rule

セーブポイント付きでNATポートフォワーディングルールを更新します（OPNsense < 26.7）。パラメータ: uuid, interface, protocol, destination_port, target_ip, target_port, description, enabled

あり

opn_delete_nat_rule

UUIDでNATポートフォワーディングルールをセーブポイント付きで削除します（OPNsense < 26.7）。パラメータ: uuid

あり

注: セーブポイント保護はOPNsense < 26.7でのみ存在します。26.7+では、これらのツールは変更を即時かつ恒久的に適用します — 書き込み操作とセーブポイントを参照してください。

DNS（13ツール）

ツール

説明

書き込み

opn_list_dns_overrides

Unboundホストオーバーライド（ローカルDNSレコード）。パラメータ: search, limit

なし

opn_list_dns_forwards

DNSフォワードゾーン（ドメイン固有のサーバー）。パラメータ: search, limit

なし

opn_dns_stats

Unboundリゾルバ統計（クエリ、キャッシュヒット、稼働時間）

なし

opn_reconfigure_unbound

保留中のDNSリゾルバ設定変更を適用します

あり

opn_add_dns_override

Unbound DNSホストオーバーライド（A/AAAAレコード）を追加して即時適用します。パラメータ: hostname, domain, server, description

あり

opn_list_dnsbl

プロバイダーとステータスを含むDNSBLブロックリスト設定を一覧表示します。パラメータ: search, limit

なし

opn_get_dnsbl

UUIDで完全なDNSBL設定を取得します（プロバイダー、許可リスト、設定）。パラメータ: uuid

なし

opn_set_dnsbl

DNSBL設定を更新します（読み取り・変更・書き込み）。パラメータ: uuid, enabled, providers, allowlists, blocklists, wildcards, など

あり

opn_add_dnsbl_allowlist

上書きせずにDNSBL許可リストにドメインを追加します。パラメータ: uuid, domains

あり

opn_remove_dnsbl_allowlist

DNSBL許可リストからドメインを削除します。パラメータ: uuid, domains

あり

opn_update_dnsbl

DNSBLブロックリストファイルを再読み込みし、Unboundを再起動します（設定変更なし、リカバリツール）

あり

opn_update_dns_override

Unbound DNSホストオーバーライドを更新して即時適用します。パラメータ: uuid, hostname, domain, server, description, enabled

あり

opn_delete_dns_override

Unbound DNSホストオーバーライドを削除して即時適用します。パラメータ: uuid

あり

DHCP（8ツール）

ツール

説明

書き込み

opn_list_dhcp_leases

ISC DHCPサーバーからのアクティブなDHCPv4リース

いいえ

opn_list_kea_leases

Kea DHCPサーバーからのDHCPv4リース。パラメータ: search、limit

いいえ

opn_list_dnsmasq_leases

dnsmasq DNS/DHCPサーバーからのDHCPv4およびDHCPv6リース。パラメータ: search、limit

いいえ

opn_list_dnsmasq_ranges

設定済みのDHCPアドレス範囲（RA設定付きのDHCPv4とDHCPv6の両方）。パラメータ: search、limit

いいえ

opn_add_dnsmasq_range

新しいDHCP範囲（Router Advertisement設定付きのIPv4またはIPv6）を作成。パラメータ: interface、start_addr、end_addr、prefix_len、ra_mode、lease_time、description

はい

opn_reconfigure_dnsmasq

保留中のdnsmasq DNS/DHCP設定変更を適用

はい

opn_update_dnsmasq_range

DHCP範囲（アドレス、リース時間、RA設定）を更新して適用。パラメータ: uuid、interface、start_addr、end_addr、prefix_len、ra_mode、lease_time、description、enabled

はい

opn_delete_dnsmasq_range

UUIDでDHCP範囲を削除して適用。パラメータ: uuid

はい

VPN（3ツール）

ツール

説明

opn_wireguard_status

WireGuardトンネルとピアのステータス（os-wireguardプラグインが必要）

opn_ipsec_status

IPsec VPNトンネルのステータス — IKE（フェーズ1）およびESP/AH（フェーズ2）セッション

opn_openvpn_status

OpenVPN接続ステータス — インスタンス、セッション、ルート

HAProxy（8ツール）

HAProxyロードバランサーの完全な設定管理（os-haproxyプラグインが必要）。

ツール

説明

書き込み

opn_haproxy_status

HAProxyサービスのステータスとバックエンドの健全性

いいえ

opn_haproxy_search

タイプ別にHAProxyリソースを検索。パラメータ: resource_type（frontends/backends/servers/actions/acls/healthchecks/errorfiles/resolvers/mailers）、search、limit

いいえ

opn_haproxy_get

特定のリソースの詳細設定を取得。パラメータ: resource_type、uuid

いいえ

opn_haproxy_configtest

適用前にHAProxy設定の構文を検証

いいえ

opn_haproxy_add

新しいHAProxyリソースを作成。パラメータ: resource_type、config（フィールド値のdict）

はい

opn_haproxy_update

既存のHAProxyリソースを更新（部分更新）。パラメータ: resource_type、uuid、config

はい

opn_haproxy_delete

UUIDでHAProxyリソースを削除。パラメータ: resource_type、uuid

はい

opn_reconfigure_haproxy

保留中のHAProxy設定変更を適用

はい

注: HAProxyの変更はセーブポイント保護を使用しません — 再設定時に即座に適用されます。opn_reconfigure_haproxyの前に必ずopn_haproxy_configtestを呼び出してください。

サービス（11ツール）

ツール

説明

書き込み

opn_list_acme_certs

ACME/Let's Encrypt証明書とそのステータス。パラメータ: search、limit

いいえ

opn_list_cron_jobs

スケジュールされたcronジョブ。パラメータ: search、limit

いいえ

opn_crowdsec_status

CrowdSecセキュリティエンジンのステータスとアクティブな決定

いいえ

opn_crowdsec_alerts

CrowdSecセキュリティアラート（検出された脅威）。パラメータ: search、limit

いいえ

opn_list_ddns_accounts

ダイナミックDNSアカウントとその更新ステータス。パラメータ: search、limit

いいえ

opn_add_ddns_account

新しいダイナミックDNSアカウントを作成。パラメータ: service、hostname、username、password、checkip、interface、description

はい

opn_reconfigure_ddclient

保留中のダイナミックDNS設定変更を適用

はい

opn_update_ddns_account

ダイナミックDNSアカウントを更新（パスワードは書き込み専用）。パラメータ: uuid、service、hostname、username、password、checkip、interface、description、enabled

はい

opn_delete_ddns_account

UUIDでダイナミックDNSアカウントを削除。パラメータ: uuid

はい

opn_mdns_repeater_status

mDNSリピーターのステータスと設定（有効、インターフェース、ブロックリスト）。os-mdns-repeaterプラグインが必要

いいえ

opn_configure_mdns_repeater

クロスVLANデバイス検出（HomeKit、Chromecast、AirPlay）用にmDNSリピーターを設定。パラメータ: enabled、interfaces

はい

診断（4ツール）

ツール

説明

opn_ping

ファイアウォールからホストにpingを送信して接続をテスト。パラメータ: host、count（1〜10、デフォルト3）

opn_traceroute

宛先までのネットワークパスをトレース。パラメータ: host、protocol（ICMP/UDP/TCP）、ip_version（4/6）

opn_dns_lookup

ファイアウォールからのDNSルックアップ。パラメータ: hostname、server（オプションのカスタムDNSサーバー）

opn_pf_states

アクティブなPFステートテーブルを照会。パラメータ: search、limit（最大1000）

セキュリティ（1ツール）

ツール

説明

opn_security_audit

包括的な11分野のセキュリティ監査: ファームウェア、ファイアウォールルール（MVC + レガシー、ポートグループ、安全でないプロトコル）、NATフォワーディング、DNSセキュリティ（DNSSEC、DoT）、システム強化（SSH、HTTPS、syslog）、サービス、証明書（ACME + システム + CA）、VPN（WireGuard設定、IPsec、OpenVPN）、HAProxy（ヘッダー、ヘルスチェック）、ゲートウェイ。検出結果はPCI DSS v4.0、BSI IT-Grundschutz、NIST 800-41、CISコンプライアンス参照でタグ付けされます。

書き込み操作とセーブポイント

書き込み操作にはOPNSENSE_ALLOW_WRITES=trueが必要です。OPNsense < 26.7では、ファイアウォールの変更はさらにOPNsenseのセーブポイントメカニズムを経由します:

  1. ファイアウォール変更の前に、セーブポイントが自動的に作成されます

  2. 変更が適用されます（ルールのトグル、追加、削除）

  3. 60秒のカウントダウンが開始されます — 確認されない場合、OPNsenseは自動的に変更を元に戻します

  4. opn_confirm_changes を返されたrevisionとともに使用して、変更を永続化します

これらのバージョンでは、AIアシスタントが悪いファイアウォール変更を行ってロックアウトされた場合、変更は60秒以内に自動的に元に戻ります。

OPNsense 26.7ではセーブポイント/ロールバックAPIが上流で削除されたため、26.7+では自動元に戻しはありません。 サーバーはバージョンカットオフをハードコードしていません: 最初のファイアウォール書き込み時にセーブポイントエンドポイントをプローブし、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は書き込みを必要としますが、セーブポイントは使用しません — サービス設定の変更を適用し、自動的に元に戻すことはできません。

IPv6サポート

MCP経由で完全自動化

  • IPv6ファイアウォールルール — ip_protocol="inet6" を使用したルールの作成（OPNsense < 26.7ではセーブポイント保護あり）

  • HAProxy IPv6バインディング — [::]:443 または [2001:db8::1]:443 のバインドアドレスを持つフロントエンド

  • HAProxy IPv6バックエンド — IPv6アドレスを持つサーバー、バックエンドでの resolvePrefer: ipv6

  • IPv6対応ダイナミックDNS — IPv6対応のcheckipメソッドを使用するDDNSアカウント

  • DHCPv6レンジ（dnsmasq） — ルーターアドバタイズメント設定付きのIPv6 DHCPレンジ

  • DNS AAAAレコード — IPv6アドレスを持つUnboundホストオーバーライド

  • IPv6診断 — ip_version="6" を使用したトレースルート、ホスト名によるping

手動でのGUI設定が必要

これらの設定はOPNsenseのMVC APIをサポートしておらず、Web GUIで設定する必要があります：

  • WAN IPv6設定 — DHCPv6プレフィックス委譲を使用したPPPoE、静的IPv6、SLAAC

  • LAN IPv6アドレス設定 — トラックインターフェースモード、静的/64割り当て、プレフィックスID

  • インターフェース割り当て — WAN/LAN/OPTロールへの物理ポートの割り当て

  • 6to4/6rdトンネル — 移行トンネルメカニズム

既知の制限事項

  • ISC DHCP / Kea DHCPv6：未実装。DHCPv6レンジとルーターアドバタイズメントにはdnsmasq（現代のデフォルト）のみがサポートされています。ISC DHCPは非推奨です。Kea DHCPv6のリース表示はAPIでは制限されています。

  • radvd：独立したツールセットとしては未実装。Dnsmasqはレンジ設定を介してルーターアドバタイズメントをネイティブに処理します。インターフェースごとに実行するRAデーモンは1つのみにしてください。

  • デュアルスタックファイアウォールルール：inet46（デュアルスタック）はMVC APIルール（opn_add_firewall_rule）では正しく機能します。ただし、レガシーXMLフィルタールール（GUI）でのinet46はPF出力を生成せずに静かに失敗します — これはレガシールールのみに影響する既知のOPNsenseバグです。

  • レガシーGUIルール：従来のOPNsense GUIで作成されたファイアウォールルールは、MVC APIからはアクセスできません。読み取り専用アクセスには opn_get_config_section("filter") を使用してください。

推奨されるIPv6移行ワークフロー

  1. 手動（GUI）： WAN IPv6を設定（ISPからのDHCPv6-PDまたは静的）

  2. 手動（GUI）： LANインターフェースを設定（プレフィックス委譲のためのトラックインターフェースモード）

  3. MCP： RAフラグ付きの opn_add_dnsmasq_range を使用してルーターアドバタイズメントを設定

  4. MCP： IPv6ファイアウォールルールを作成（NDP/RA/PMTUDのためにICMPv6を許可する必要があります）

  5. MCP： opn_add_dns_override を使用してIPv6 DNSレコードを追加

  6. MCP： IPv6 checkipメソッドを使用してダイナミックDNSを設定

  7. MCP： HAProxyフロントエンドにIPv6バインドアドレスを追加

  8. MCP： opn_ping、opn_traceroute（ip_version="6"）、opn_gateway_status で検証

バージョン互換性

OPNsenseバージョン

ステータス

24.7 (Thriving Tiger)

サポート対象

25.1 (Ultimate Unicorn)

サポート対象

25.7 (Visionary Viper)

サポート対象（snake_case APIを自動検出）

26.1+

サポート対象

サーバーは最初の接続時にOPNsenseのバージョンを自動検出し、正しいAPIエンドポイント命名規則（25.7以前はcamelCase、25.7以降はsnake_case）を選択します。

ファイアウォールルールに関する注意： opn_list_firewall_rules はMVC/自動化APIで管理されるルールを表示します。OPNsense GUIで設定されたルールは、このAPIからはアクセスできないレガシーフォーマットを使用します。これは既知のOPNsenseの制限事項です。

トラブルシューティング

接続の問題

「接続が拒否されました」またはタイムアウトエラー

  • OPNSENSE_URL が /api で終わっていることを確認（例：https://192.168.1.1/api）

  • 非標準ポートを使用する場合は、ポートを含めてください：https://192.168.1.1:10443/api

  • OPNsense Web GUIが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/自動化ルールのみを表示し、レガシーGUIルールは表示しません

  • 自動化APIまたは opn_add_firewall_rule を使用してルールを作成すると表示されます

opn_ping がタイムアウトする

  • ファイアウォールがターゲットホストへのルートを持っていない可能性があります

  • opn_gateway_status でゲートウェイのステータスを確認

  • デフォルトのタイムアウトは30秒（30ポーリングサイクル）です

opn_download_config に [REDACTED] の値が表示される

  • これはセキュリティ上のデフォルト動作です。パスワードとキーを含めるには include_sensitive=true を渡してください（AI会話での使用には注意が必要）

書き込み操作が「writes not enabled」で失敗する

  • MCPサーバー設定で OPNSENSE_ALLOW_WRITES=true を設定

  • これは安全のためデフォルトで意図的に無効化されています

セーブポイント確認が失敗する

  • revision パラメータは、書き込み操作で返されたものと正確に一致する必要があります

  • 確認は60秒以内に行う必要があります。そうしないと変更は自動的に元に戻ります

  • OPNsense 26.7以降にはセーブポイントAPIがありません：書き込みツールは空の 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

ベストプラクティス

一般的なファイアウォール設定タスクのためのドメイン固有ガイド：

これらのガイドは、実際のMCPツール使用パターンを示し、各アプローチの背後にあるセキュリティ上の考慮事項を説明しています。

コントリビューション

詳細なガイドラインについては CONTRIBUTING.md を参照してください。重要なポイント：

  1. すべてのテストはモックされたAPIレスポンスを使用する必要があります — 実際のOPNsenseに接続しないでください

  2. 重複するツールはありません — 各ツールには明確な目的が必要です

  3. 明確なdocstringを書いてください — それらはAIがツールを選択するための唯一のガイドです

  4. 構造化データ（dict）を返し、フォーマットされた文字列は返さないでください

  5. 提出前に make validate を実行してください

ライセンス

MIT

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
5wRelease cycle
5Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • OPNsense MCP Server

    Pixelworlds
    A
    license
    Not graded
    quality
    F
    maintenance
    A modular MCP server that provides access to over 2,000 OPNsense firewall management methods through 88 specialized tools. It enables AI assistants to securely manage firewall rules, network interfaces, and system diagnostics using a type-safe TypeScript interface.
    370
    73
    MIT

  • OPNsense MCP Server

    gabrielion
    A
    license
    Not graded
    quality
    A
    maintenance
    This MCP server enables AI agents to inspect and modify an OPNsense firewall via natural language, using a compact set of generic tools and a resource registry to cover 96 CRUD operations.
    29
    AGPL 3.0

View all related MCP servers

Related MCP Connectors

  • royal-mcp

    Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.

  • secureflows-mcp

    MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.

  • microservices.sh

    MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lucamarien/opnsense-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server