OPNsense MCP

ファイアウォールについて、自然な言葉で質問できます。

OPNsense 向けの読み取り専用ツールが4つあります。デフォルトでは読み取り専用で、検証済みの内容についてのみ具体的に回答します。

クイックスタート · ツール · セットアップガイド · 検証方法 · ステータス

プレビュー: AI アシスタントが OPNsense システムを調査できる小さな MCP サーバーです。明示的に有効化された場合にのみ、確認・バックアップ・監査の枠組みの下で、1種類のファイアウォールエイリアスの作成または削除を行います。デフォルトでは読み取り専用です。パッケージ化されたサーバーは、合成 HTTPS ターゲットと使い捨ての OPNsense 26 VM の両方に対して動作検証されています。

日常的な言葉で質問してください。サーバーはエージェントに対し、まず事実から始め、ネットワーク用語を説明し、一度に1つの有用な確認質問を行い、観察結果と仮説を明確に区別するよう指示します。

クイックスタート

読み取り専用で、約15分かかります。macOS または Linux 上で、Node.js 22.19 以降（メジャー22以内）が必要です。

1. ファイアウォールの認証情報を保存する

npx -y @gabrielion/opnsense-mcp configure

HTTPS オリジン、API キーとシークレット、オプションの CA ファイルを尋ねられます。入力内容はエコーされず、プロセス引数として渡されることもありません。先にキーを作成する必要がありますか？セットアップガイド に OPNsense 側の手順がスクリーンショット付きで記載されています。

2. アシスタントを接続する

claude mcp add opnsense --transport stdio --env READ_ONLY=true -- npx -y @gabrielion/opnsense-mcp

[mcp_servers.opnsense]
command = "npx"
args = ["-y", "@gabrielion/opnsense-mcp"]

[mcp_servers.opnsense.env]
READ_ONLY = "true"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["npx", "-y", "@gabrielion/opnsense-mcp"],
      "environment": { "READ_ONLY": "true" }
    }
  }
}

3. 質問してみる

OPNsense のシステムステータスはどうなっていますか？

ファイアウォールではどのサービスが実行されていますか？

最初に /mcp を実行してください。サーバーが connected と表示されるはずです。追加しても認証情報は検証されないため、connected が実際の接続確認のシグナルです。

[!TIP] 手元にファイアウォールがない、または自分の環境に向ける準備ができていない場合？ npm run test:product1b は使い捨ての OPNsense VM を起動し、あなたの認証情報を使わずに独自の最小権限アカウントを作成し、読み取り面全体を検証してからクリーンアップします。

Related MCP server: OPNsense MCP Server

現在利用できる機能

デフォルトでは、インストールされたサーバーは4つの読み取り専用ツールを公開します:

• server_status は MCP プロセスとその読み取り専用状態を確認します。

• opn_describe はエージェントが使用する前に、表示されているリソースを説明します。

• opn_get はシングルトンリソース system.status を読み取ります。

• opn_list はコレクションリソース core.services と firewall.alias をページングします。エイリアスについては ホストエントリのみ を一覧表示し、報告される合計数もそれらを数えます。他のエイリアスタイプは表示されません。

3つの MCP プロンプトも常に登録されています — diagnose_network_problem、publish_internal_service、block_domain_for_device です。これらは読み取り専用の準備プランのみを生成し、何も実行しません。

READ_ONLY=true がデフォルトであり、この設定下では書き込みツールは一覧表示もディスパッチもされません。

opn_create と opn_delete という2つの実験的な書き込みツールが存在し、これらは firewall.alias のホストエントリのみを操作します。3つの条件とサポートされるトランスポートが、それらが 一覧表示 されるかどうかを決定します:

• READ_ONLY=false;

• ENABLED_FEATURE_FLAGS に experimental-alias-write が含まれる;

• ALLOWED_RESOURCES が firewall.alias を明示的に指定する。許可リストが存在しないか空の場合、すべての読み取りを許可し、書き込みは一切許可しません。許可リストは読み取りもフィルタリングするため、引き続き必要なすべてのスコープを指定してください。例: ALLOWED_RESOURCES=server.status,system.status,core.services,firewall.alias;

• トランスポートが stdio または Streamable HTTP であること。レガシー SSE では一覧表示もディスパッチもされません。

4つ目の条件は一覧表示ではなく 呼び出し を管理します。クライアントがフォーム引き出し（form elicitation）をネゴシエートしている必要があります。それができないクライアントはツールを表示できますが、チャレンジや書き込みの前に、すべての試行で CONFIRMATION_UNAVAILABLE で拒否されます。

すべての書き込みは、この固定された一連の処理をこの順序で実行します: 認可、変更内容を明示する人間による確認、ターゲットに対する排他ロック、副作用のない事前チェック、編集済み監査インテント、検証済み変更前バックアップ、観測された状態が変わっていないことの再確認、書き込み、結果の検証、最終監査レコード、ロックの解放。バックアップ後のすべての失敗はバックアップを保持し、盲目的に復元することはありません。

これらの書き込みが実験的であるのには理由があります。 変更前バックアップはプロセスごとの一時ディレクトリに書き込まれ、サーバーがシャットダウンすると削除される ため、後から参照することはできません。監査はメモリ内リングで、最新の1024レコードのみを保持し（書き込みごとに2レコード）、永続化された形式もそれを読み取るツールもありません。ロックはプロセスローカルであるため、同じファイアウォールを指す2つのサーバーは互いに排他しません。

この枠組みが保証することは狭いですが現実的です: 検証済みバックアップと監査インテントが最初に記録されない限り、書き込みは拒否されます。復元もロールバックもありません — 変更適用後に失敗が発生した場合、変更は適用されたままとなり、復旧は OPNsense 自身の設定履歴を通じて手動で行います。この状態を永続化することが次のマイルストーンです。

簡単なローカル検証

要件: Node.js 22.19 以降（メジャー22以内）、npm、macOS または Linux。

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
npm ci --ignore-scripts &&
npm run test:product1a &&
npm run build

npm run test:product1a はクリーンな npm ターボールを作成し、分離されたコンシューマープロジェクトにインストールし、別途所有する合成 HTTPS OPNsense ターゲットに接続し、生の MCP stdio を通じて3つの OPNsense ツールすべてを呼び出し、シークレットが決して表示されないことを確認し、EOF で閉じ、すべてのフィクスチャを削除します。

OPNsense インスタンスを接続する

認証情報を提供するサポートされている方法は対話型コマンドで、正しい所有権とモードでプライベートファイルを書き込みます。クローンからは、ビルド済みエントリポイントのサブコマンドです:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
node dist/main.js configure

レジストリからインストールした場合、同じサブコマンドは npx -y @gabrielion/opnsense-mcp configure です。

HTTPS オリジン、API キー、API シークレット、オプションの CA ファイルと TLS サーバー名をプロンプトで尋ねます。シークレットはエコーされず、プロセス引数にも表示されません。Windows での実行と引数の受け付けを拒否します。

常にプラットフォームのパスに書き込み、OPNSENSE_CONFIG_FILE を無視します。これはサーバー側の変数です:

• macOS: ~/Library/Application Support/opnsense-mcp/config.json;

• Linux: $XDG_CONFIG_HOME/opnsense-mcp/config.json、それ以外の場合は ~/.config/opnsense-mcp/config.json。

サーバーは同じパスを検出するため、この変数は別の場所に保存されたファイルを読み取る場合にのみ必要です。所有する各ディレクトリはモード 0700 で作成され、ファイルはモード 0600 で作成されます。シンボリックリンク、外部所有者、安全でない祖先ディレクトリは拒否されます。

2つの実用的な制限があります: 既存の設定を 上書きすることは決してない ため、キーをローテーションするにはまずファイルを削除してください。また、両方のストリームで実際のターミナルが必要なため、パイプや CI では実行できません。すべての失敗は意図的に単語 Error のみを出力します — 診断情報は意図的に不透明にされており、プライベートパスや認証情報が漏れることはありません。

あるいは、リポジトリの外で JSON ファイルを自分で作成し、モード 0600 で保護します:

{
  "url": "https://192.0.2.1",
  "apiKey": "your-dedicated-read-only-api-key",
  "apiSecret": "your-api-secret",
  "caFile": "/absolute/path/to/your-ca.pem",
  "tlsServerName": "firewall.example.internal"
}

ファイルは、現在のユーザーが所有する通常の非シンボリックリンクファイルで、絶対パスにあり、モードが正確に 0600、ハードリンクが正確に1つ、サイズが最大16 KiB である必要があります。0400 も拒否されます。url は正確に1つの HTTPS オリジンである必要があります。ファイアウォール証明書が信頼された CA にすでにチェーンしている場合、caFile はオプションです。URL が IP アドレスを使用しているが、検証済み証明書が DNS 名を使用している場合、tlsServerName はオプションです。TLS 検証は常に有効のままです。専用の最小権限 OPNsense キーを使用してください。認証情報をチャットやコマンド引数に貼り付けないでください。

トランスポート。 stdio がデフォルトであり、パッケージ化された検証でエンドツーエンドに実行される唯一のトランスポートです。dist/main.js は常に stdio で起動します。Streamable HTTP トランスポートは、MCP_HTTP_ENABLED の背後にある別のエントリポイント（npm run start:http）として存在し、Host/Origin 許可リストと32文字以上のベアラー MCP_HTTP_TOKEN を持つループバックにバインドされます。これはクライアントスモークテストの対象ではないため、クライアントサポートの主張は行われません。レガシー SSE 互換サーフェスは MCP_LEGACY_SSE_ENABLED の背後に存在し、これには追加で MCP_HTTP_ENABLED=true が必要です — 単独で設定すると起動エラーになります — また、確認付き書き込みツールを公開することはありません。

プロトコルクリーンな stdio サーバーを直接実行するには:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
OPNSENSE_CONFIG_FILE="/absolute/path/to/opnsense.json" READ_ONLY=true node dist/main.js

開発やテストを本番ファイアウォールに向けないでください。実稼働作業には以下の使い捨て VM 検証を使用してください。

使い捨て OPNsense 26 検証

macOS または Linux で、QEMU と Node.js 22 をインストールしてから実行します:

npm run vm:doctor
npm run test:product1b

vm:doctor はマシンを変更せずに、不足している各ホスト依存関係を報告します。test:product1b はライブテスト全体を所有します: 固定された公式 OPNsense 26.7 nano イメージを検証してキャッシュし、ローカル VM を1つ起動し、オペレーターの認証情報なしでシリアルコンソール経由で使い捨ての最小権限 API ユーザーを作成し、この npm パッケージをパックしてインストールし、1つの MCP セッションを通じて server_status、opn_describe system.status、opn_get system.status、opn_list core.services を呼び出し、その後 VM を停止してオーバーレイ、API 認証情報、証明書、一時パッケージを削除します。初回実行では約557 MB のアーカイブをダウンロードし、ユーザーキャッシュに3 GiB の読み取り専用ベースイメージを作成します。

歴史的な Product 1B の証拠は、2つのリモート呼び出しのみの証明のままです: GET /api/core/system/status と POST /api/core/service/search です。サニタイズされた機械可読な証拠には、正確なホスト、QEMU、ファームウェア、トランスポート、クリーンアップチェックも記録されていますが、ファイアウォールデータや認証情報は保持されません。

エイリアス書き込み実装は、変更前バックアップに GET /api/core/backup/download/this をターゲットにし、次に POST /api/firewall/alias/searchItem、addItem または delItem/{uuid}、そして reconfigure 適用を行います。これらのエンドポイントの詳細は、決定的な合成ターゲットカバレッジを持っています。Product 3 は使い捨て VM 上で以下のみを証明します: 書き込み可能なサーフェスと、この正確な firewall.alias ライフサイクル — 不在、作成、存在、削除、不在 — に続いて VM クリーンアップと残留物なしチェックです。コミットバインドされた Product 3 VM アテステーションには、テストされたコミットとツリー、固定されたファームウェアイメージ、ポリシー入力、固定されたライフサイクルチェックが記録されていますが、ファイアウォールデータや認証情報は保持されません。Product 3 アテステーションは、本番使用、永続状態、永続バックアップ、永続監査証跡、復元、自動ロールバックを証明するものではありません。

復元ラウンドトリップはさらに、同じエイリアス変更を API 経由ではなく、使い捨て VM のコンソール経由で直接元に戻し、その後 API を再観測して変更が消えたことを確認します。復元ラウンドトリップ Product 3 VM アテステーションには、テストされたコミットとツリー、同じ固定ファームウェアイメージとポリシー入力、エイリアスライフサイクルチェック、バックアップ復元済みおよび状態復元済みチェックが記録されています。これもファイアウォールデータや認証情報を保持せず、node scripts/vm/product3-restore.mjs --attestation-out "$PWD/docs/evidence/product3-restore-vm.json" で生成されます。

使い捨てアカウントの権限。 アカウントは、まさにこれらの標準ACLのみで作成され、それ以外は何も付与されません。両方のACLプロファイルは、それぞれの正確なシナリオでのみライブエビデンスを持ちます。読み取り専用プロファイルはProduct 1B、エイリアス書き込みプロファイルはProduct 3です。

• 読み取り専用アカウント: page-system-status、page-status-services、user-config-readonly;

• エイリアス書き込みアカウント: page-system-status、page-status-services、 page-diagnostics-configurationhistory、page-firewall-alias-edit。

user-config-readonly は、エイリアス書き込みアカウントから意図的に除外されています。これが含まれると、OPNsenseの可変モデルコントローラがエイリアス保存を拒否することを確認したためです。page-diagnostics-configurationhistory は、変更前の設定バックアップ要求のために付与されています。どちらの記述も、引用された上流のマッピングではなく、私たち自身のブートストラップ経験に基づいています。

OpenCode

プロジェクトレベルの opencode.json を追加します（両方の絶対パスを置き換えます）:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["node", "/absolute/path/to/OPNSenseMCP/dist/main.js"],
      "environment": {
        "READ_ONLY": "true",
        "OPNSENSE_CONFIG_FILE": "/absolute/path/to/opnsense.json"
      }
    }
  }
}

次に opencode mcp list を実行します。opnsense が接続されているはずです。コミット済みのスモークエビデンスは、インストール済みのtarballと合成HTTPSターゲットに対するOpenCode 1.18.16と opencode/deepseek-v4-flash-free のみを対象としています。ツール/結果のダイジェストを記録しており、ファイアウォールのデータや認証情報は含みません。機械可読なエビデンス を参照してください。

他のMCPクライアントも同じstdioコマンドを起動できますが、独自のバージョン管理されたスモークが合格するまで、クライアント固有のサポート主張は行われません。

このプレビューのテスト方法

• 厳格なTypeScript、フォーマット、lint、ライセンスヘッダー、および決定的なユニット/統合テスト。

• クリーンなnpm pack/installに加え、合成ターゲットに対するTLS、Basic認証、レスポンス検証、シークレットの編集、シャットダウン、およびクリーンアップ。

• 使い捨てOPNsense 26.1.6 VMに対する2つのProduct 1Bリモートコールの履歴的なクリーンなnpm pack/install。VMの所有権、固定イメージの整合性、分離された認証情報、TLSピニング、逆順のクリーンアップを含みます。

• 書き込み可能なサーフェスと正確なホストエイリアスのライフサイクル（不在、作成、存在、削除、不在）に対する、使い捨てOPNsense 26.7 VMでのコミットバインドされたProduct 3実行。その後、VMクリーンアップと残留物なしのチェックが続きます。

• 合成ターゲットの証明と両方のVMランナーのための密閉型パッケージインストール。コンシューマは、ロックから導出されたループバック専用npmレジストリからすべての依存関係を解決し、空のキャッシュと到達不能なプロキシを使用するため、インターネットアクセスは関与せず、上流のリリースがインストール内容を変更することはできません。

• プロトコルバージョン 2025-11-25 とドラフト 2026-07-28 に対するターゲットを絞ったMCP相互運用性チェック。

• opencode/deepseek-v4-flash-free を使用した実際のOpenCode 1.18.16ルーティングスモークが1回。

完全な開発状態とマシン間のハンドオフは、docs/project-status.md に記録されています。計画されている標準的なエージェント評価は、DeepEvalおよびOPNsenseエージェント評価設計 で指定されています。これは、Claude CodeのMCPツール使用と最終レスポンスを評価し、同時に使い捨てVM状態の決定的なMCP読み戻しを別途要求します。これらのテストとベンチマークスコアは、まだ実装も主張もされていません。

これらのチェックは、パッケージ、合成読み取りパス、前述の2つの履歴的なProduct 1Bリモートコール、および上記の範囲内のライフサイクルのみをカバーします。以下を証明するものではありません:

• インターネット上の公開DNS、ACME、またはHAProxyへの露出;

• 本番ファイアウォールに対する動作;

• 永続的なバックアップまたは永続的な監査証跡。両方とも存在しますが、プロセスの存続期間のみです;

• 復元、または適用された変更の自動ロールバック;

• firewall.alias のホストエントリ以外への書き込み;

• 最初の100ホストエイリアスを超える保証。変更前の状態ダイジェストと読み戻しはどちらも100件の単一ページを読み取るため、それを超えると、作成は未検証の結果を報告する可能性があり、削除はエントリが読み取ったページに存在しなかったことのみを証明できます;

• ネイティブWindowsのインストールまたはクライアント操作;

• 完全なエージェントベンチマークまたはベンチマークスコア。

生のAPIディスパッチ、自由形式のシェル/SSH、バルクIaC、ダッシュボード、および広範なレガシー互換性は含まれていません。

製品ロードマップとリクエスト例

変更安全性エンベロープ（スコープ付き認可、人間による確認、検証済みバックアップ、編集済み監査、結果検証、フェイルクローズドなクリーンアップ）は実装され、合成HTTPSターゲットに対して証明されています。次のマイルストーンは、その状態を永続化することです。永続的な状態ルート、プロセス間ロック、追記専用監査、およびローカルの reconcile コマンドにより、保証が再起動後も存続します。その後にのみ、エイリアス書き込みの experimental ラベルが見直されます。

その後のガイド付きワークフローは、意図的にユーザーレベルの目標です。例えば:

• 「私のラップトップは毎晩インターネットに接続できなくなります。調査して、見つけたことを説明してもらえますか?」

• 「他のデバイスに影響を与えずに、子供のタブレットに対してのみTikTokをブロックしてください。」

• 「このサービスを、わかりやすいDNS名、内部証明書、リバースプロキシを使用して社内に公開してください。」

これらの3つのワークフローはロードマップの例であり、Product 1Aの主張ではありません。公開DNS、Let's Encrypt、HAProxyを使用したインターネット向け公開は、安全な書き込みとプライベートVMカバレッジの後の、より長期的なラボのマイルストーンです。

配布ステータス: npmで @gabrielion/opnsense-mcp として公開されているため、npx -y @gabrielion/opnsense-mcp でリリース済みサーバーが実行されます。git URLからのインストールは、prepare スクリプトを通じて独自の dist/ をビルドします。パッケージ化された証明は、どちらの場合もロックから導出されたループバックレジストリによって提供されるローカルビルドのtarballをインストールするため、それらが検証するのはレジストリのコピーではなく、このツリーです。バージョン管理やアップグレードの保証はまだ提供されていません。

プラットフォームステータス: macOSとLinuxが現在検証済みの開発ホストです。ネイティブWindowsは引き続き必須の製品ターゲットですが、パッケージとクライアントのサポートは、後の windows-2025 ゲートが合格するまで主張されません。

ライセンスと商標

AGPL-3.0-or-laterの下でライセンスされています。LICENSE を参照してください。AGPLは商用利用を許可しつつ、ネットワーク利用を含む対象ソースの公開を要求します。OPNsenseはDeciso B.V.の商標です。この独立したプロジェクトは、Deciso B.V.またはOPNsenseプロジェクトと提携、スポンサー、または推奨関係にありません。