Opnsense Mcp

OPNsense MCP サーバー

OPNsense ファイアウォールの操作（ARP、DHCP、ログ、ルール、インターフェース、システムステータス、パケットキャプチャ）に対応する MCP サーバーです。

次の2つのデプロイモードのいずれかを使用します。

• STDIO（ローカル）：サーバープロセスを直接実行する Cursor／Claude Code／Continue に最適です。
• SSE（一元管理）：HTTPS 経由で共有する、長時間稼働のサービスに最適です。

デモ

Claude Code CLI でファイアウォールに問い合わせます。実際のネットワークデータを使ったライブデモです。

このプロジェクトを作った理由

ログの確認や ARP データの取得のたびに、SSH でファイアウォールに接続するのが面倒になったため、このプロジェクトを作りました。今では Claude に次のように質問できます。

• 「今、ネットワークで何が起きていますか？」
• 「最新のファイアウォールブロックを表示してください」
• 「あのホストについて教えてください」
• 「不審なトラフィックのパケットをキャプチャしてください」

Claude は MCP 経由でファイアウォールに問い合わせ、分析とコンテキストをまとめて提供します。ホームラボとビジネス環境のどちらでも同様に使用できます。

クイックスタート

1) ローカル環境のセットアップ（両モードで必須）

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
cp examples/.env.example ~/.env

~/.env を編集します。

OPNSENSE_API_KEY=your_api_key
OPNSENSE_API_SECRET=your_api_secret
OPNSENSE_FIREWALL_HOST=your.firewall.host
# HTTP/SSE only; stdio ignores it. Generate with: openssl rand -hex 32
MCP_SECRET_KEY=

2) モードを選択

モード A：STDIO（ローカル IDE／クライアント）

MCP クライアントが mcp_start.sh を起動するように設定します。

{
  "mcpServers": {
    "opnsense-mcp": {
      "command": "/bin/bash",
      "args": ["/absolute/path/to/opnsense-mcp/mcp_start.sh"],
      "cwd": "/absolute/path/to/opnsense-mcp"
    }
  }
}

詳しい手順については、docs/GETTING_STARTED.md を参照してください。

モード B：SSE（一元管理サービス）

Linux インストーラーを実行します（Podman + quadlet + Caddy TLS）。

sudo bash deploy/install.sh

クライアントは次の場所に接続します。

https://<your-hostname>/sse

すべてのリクエストで Authorization: Bearer <MCP_SECRET_KEY> を送信する必要があります。キーが空欄またはプレースホルダーの場合、サーバーは HTTP トランスポートでの起動を拒否します。

デプロイに関するドキュメント：

• docs/CENTRALIZED_DEPLOY_SPEC.md
• deploy/README.md
• deploy/TLS.md

利用可能な機能

主なツール：

• 検出：arp、dhcp、lldp
• 監視：system、get_logs、packet_capture
• ファイアウォールルール：fw_rules、mkfw_rule、set_fw_rule、toggle_fw_rule、rmfw_rule
• インターフェース：interface_list

全リファレンス：docs/REFERENCE/FUNCTION_REFERENCE.md

新機能（2026年6月）

最近、5件の PR がマージされました。詳しい内容と使用例については、docs/FEATURES_UPDATE.md を参照してください。

• Streamable HTTP トランスポート — ネイティブの FastMCP サーバーが stdio、sse、streamable-http（MCP 仕様 2025-03-26）をサポートします。deploy/install.sh を使ってデプロイします。
• DHCP client_id（DUID）対応 — mk_dhcp_host と move_dhcp_host では、ステートフル DHCPv6 の照合に使用する DUID をオプションで指定できます。
• Semver イメージタグ — main ブランチのビルドには、pyproject.toml のバージョンより次のパッチバージョンのプレリリースタグ（1.0.0 の後は 1.0.1-dev.a1b2c3d）、またはリリースタグ（1.0.0）が付与されます。
• コンテナレジストリ — 固定タグのみ対応し、:latest は拒否されます。OPNSENSE_MCP_IMAGE_REPO を設定するか、--build-local を使ってローカルでビルドしてください。
• install.sh の readonly 修正 — install.sh と lib.sh 間の Bash readonly の競合を解消しました。

ユースケース

• ホームラボのネットワークトラブルシューティング — ターミナルからファイアウォールログを照会し、何が起きているかについて Claude の分析を得ます。
• セキュリティ運用 — 「過去1時間のブロックを分析して」のように、インシデントの初期調査を自動化します。
• インフラストラクチャの自動化 — ファイアウォールの状態を動的に照会する、MCP 対応スクリプトを作成します。
• DevOps のトラブルシューティング — SSH 接続なしで VLAN／インターフェースのステータスをすばやく確認します。

フィードバック

最初の10人のユーザーからのフィードバックをツールに反映します。バグを見つけた場合やアイデアがある場合は、issue またはディスカッションを投稿してください。

レビューの際に最初に確認する場所

scripts/risk_map.py は、git の履歴（変更頻度 × 修正密度）からソースファイルの不具合発生可能性を順位付けします。これにより、レビューではリスクの高いファイルから確認でき、早めに終了できます。バグを見つけるのではなく、バグが集中している場所を見つけます。

python3 scripts/risk_map.py --top 15

CI は、マージをブロックしないアドバイザリー Insights ワークフローで、すべてのプルリクエストに対して複雑度レポート（radon）およびセキュリティパターンの検査（bandit）と併せてこのスクリプトを実行します。ビルドをブロックするしきい値の導入は、数値への信頼が得られてから行います。

ドキュメント一覧

• まずはこちら：docs/GETTING_STARTED.md
• Claude Code の詳細：docs/CLAUDE_CODE_INTEGRATION.md
• SSE 集中管理仕様：docs/CENTRALIZED_DEPLOY_SPEC.md
• コントリビューターガイド：docs/DEVELOPMENT/CONTRIBUTING.md
• ブランドアセット：docs/assets/

ライセンス

このプロジェクトはMIT Licenseのもとで公開されています。