mcp-pfsense

mcp-pfsense

Claude、ChatGPT、Copilot などの AI アシスタントを通じて pfSense ファイアウォールを管理する MCP サーバーです。

必要条件：pfSense インスタンスに pfrest パッケージがインストールされていること（REST API を提供します）。

機能

7 カテゴリーにわたる 20 個のツール：

カテゴリー	ツール	説明
システム	get_system_status, get_interfaces	バージョン、CPU、メモリ、稼働時間、温度、ネットワークインターフェース
ファイアウォール	list_firewall_rules, add_firewall_rule, delete_firewall_rule, list_firewall_aliases	インターフェースで絞り込めるルール管理、エイリアス一覧
DHCP	list_dhcp_leases, list_dhcp_static_mappings, add_dhcp_static_mapping, delete_dhcp_static_mapping	アクティブなリース、IP アドレスの予約
DNS	list_dns_host_overrides, add_dns_host_override, delete_dns_host_override	Unbound DNS Resolver のホストオーバーライド
保留中の変更	get_pending_changes, apply_changes	サブシステム（ファイアウォール、DHCP、DNS）ごとにステージングされた変更を確認し、適用します
監視	get_gateway_status, get_arp_table, list_services, get_firewall_logs	ゲートウェイの状態、接続デバイス、サービスの状態、最近の生のファイアウォールログエントリー
サービス	restart_service	任意の pfSense サービスを再起動します

安全性

• 破壊的な操作（ルールの削除、マッピングの削除、サービスの再起動、変更の適用）には2 段階の確認が必要です。最初の呼び出しではツールが警告を返し、confirm=true を指定して再度呼び出した場合にのみ実行されます。
• 書き込みはステージングされ、すぐには反映されません。 pfSense WebGUI と同様に、add_* と delete_* は設定に変更を保存しますが、有効化はしません。ツールの応答にはその旨が記載されます（applied: false と pending の注記）。apply_changes(subsystem, confirm=true) で有効化すると、そのサブシステムが再読み込みされます。これには、WebGUI で人がステージングした変更も含まれます。または、1 回限りの変更を明示的に行う場合は、書き込み時に apply=true を指定してください。この 2 つの明示的な手順のいずれかを行わない限り、アシスタントによる操作がパケットフィルターに反映されることはありません。
• delete_dhcp_static_mapping には、マッピングの interface（list_dhcp_static_mappings における parent_id）と mapping_id を指定します。マッピングは両方の値で指定します。

インストール

# Using uvx (recommended)
uvx mcp-pfsense

# Using pip
pip install mcp-pfsense

前提条件

1. pfrest パッケージがインストールされた pfSense
2. API アクセス権を持つユーザーアカウント（通常は admin）

設定

環境変数を設定します：

変数	必須	デフォルト	説明
PFSENSE_HOST	はい	—	pfSense のホスト名または IP アドレス
PFSENSE_PASSWORD	はい	—	API ユーザーのパスワード
PFSENSE_USERNAME	いいえ	admin	API ユーザー名
PFSENSE_PORT	いいえ	443	API ポート
PFSENSE_SCHEME	いいえ	https	http または https
PFSENSE_VERIFY_SSL	いいえ	false	SSL 証明書を検証するかどうか

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "pfsense": {
      "command": "uvx",
      "args": ["mcp-pfsense"],
      "env": {
        "PFSENSE_HOST": "10.10.10.1",
        "PFSENSE_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add pfsense -- uvx mcp-pfsense

続いて、シェルまたは .env ファイルで環境変数を設定します。

使用例

接続したら、AI アシスタントに次のように尋ねます：

• 「pfSense のシステム状態は？」
• 「LAN インターフェースのファイアウォールルールをすべて表示して」
• 「アクティブな DHCP リースを一覧表示して」
• 「nas.home.lan が 10.10.10.50 を指す DNS エントリーを追加して」
• 「ネットワークに接続されているデバイスは？」（ARP テーブル）
• 「ゲートウェイの状態とレイテンシを表示して」
• 「最新のファイアウォールログエントリーを 50 件表示して」（読み取り専用の get_firewall_logs）
• 「LAN で TCP ポート 8080 を許可するファイアウォールルールを作成して」
• 「MAC アドレス aa:bb:cc:dd:ee:20 に IP アドレス 10.10.10.60 を予約して」

API 互換性

• pfSense: 2.7.x および 2.8.x
• pfrest: REST API v2 — list_dhcp_static_mappings を除き、v2.x のすべてのリリース。list_dhcp_static_mappings には v2.7.0 以降が必要です（このリリースで追加された /services/dhcp_server/static_mappings コレクションエンドポイントを使用します）。
• Python: 3.11 以降

各ツールが使用するエンドポイント、パラメーター、エンコーディングは、pfrest v2 のエンドポイント定義をもとにした tests/test_client_endpoints.py と tests/test_wire_format.py で固定されています。0.2.0 より前のバージョンでは、pfrest v2 に存在しない複数のエンドポイントが呼び出されていました（トラブルシューティングを参照）。

注: pfrest は nginx（デフォルトではポート 80）で動作し、pfSense WebGUI（ポート 443 の lighttpd）とは別です。pfrest が標準以外のポートで設定されている場合は、PFSENSE_PORT と PFSENSE_SCHEME を適切に設定してください。

トラブルシューティング

get_system_status と get_arp_table のみ動作し、それ以外はすべて 400/404 を返す

mcp-pfsense 0.1.1 以前では、一覧取得に単数形のエンドポイント（/interface、/firewall/rule、/firewall/alias）と、pfrest v2 では提供されない従来のパス（GET 用の /status/dhcp_leases、/services/dhcpd/static_mapping、/services/unbound/host_override、/status/gateway、/status/service）を呼び出していました。0.2.0 以降にアップグレードしてください。

list_services やその他の読み取り操作で 403 が発生する

pfrest はエンドポイントごとに API ユーザーの権限を確認します。必要なエンドポイントの api-v2-* 権限（または完全なアクセス権限が必要な場合は page-all）を、System → User Manager でユーザーに付与してください。

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

MCP Python SDK 2.0 では、mcp-pfsense 0.1.1 以前がインポートするモジュールが削除されたため、新規インストール（uvx mcp-pfsense、pip install）では起動時に失敗していました。mcp<2 を固定する 0.2.0 以降にアップグレードしてください。古い mcp-pfsense を使い続ける必要がある場合は、uvx --with "mcp<2" mcp-pfsense を使用してください。

ルール／マッピング／オーバーライドを作成したが、反映されない

これはデフォルトの動作です。書き込みはステージングされます（安全性を参照）。get_pending_changes(subsystem) で確認し、apply_changes(subsystem, confirm=true) で適用するか、WebGUI で適用してください。書き込みが 200 を返しても何も保存されない場合は、pfrest の read_only 設定が有効になっています（System → REST API → Settings）。

開発

git clone https://github.com/antonio-mello-ai/mcp-pfsense.git
cd mcp-pfsense
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint and type check
ruff check .
mypy src/

ライセンス

MIT