PAN-OS MCP Server

A token-efficient MCP server for Palo Alto Networks PAN-OS firewalls and Panorama, built around three principles:

1. Lean responses by default. Every list-returning tool exposes only the fields you actually need to answer the question. Verbose responses are opt-in. Typical 40-70% token reduction vs. dump-everything alternatives.
2. Default-deny RBAC. With no environment configuration, the server exposes only read tools. Writes, commits, and raw API access require explicit opt-in via PANOS_MODE.
3. TLS verification on by default. Self-signed certs require an explicit opt-out or a custom CA bundle — no silent man-in-the-middle exposure.

137 tools across system, diagnostics/troubleshooting, network, security, objects, NAT, user-ID, admin, VPN, Panorama, logs, threat, certificates, licenses, utility, and aggregation surfaces.

Permission Modes

Tools above the active mode are not registered with the MCP server — the LLM never sees them, so there is nothing to call. Default mode is read.

Setup

Prerequisites

• [uv](https://docs.astral.sh/uv/) (recommended) — manages Python and dependencies for you
• or Python 3.13+ with pip
• A PAN-OS firewall or Panorama with the XML API enabled, plus an API key (see below)

Getting a PAN-OS API key

PAN-OS issues API keys via the /api/?type=keygen endpoint. The key inherits the admin account's RBAC — there is no separate "API role," so a read-only admin's key cannot push config even if PANOS_MODE=admin.

Best practice: create a dedicated service account (e.g. apiread) with a Superuser (read-only) dynamic role for PANOS_MODE=read. Issue a separate key from an account with write permissions for higher tiers.

curl:

curl -k -X POST "https://fw.example.com/api/?type=keygen" \
  --data-urlencode "user=apiread" \
  --data-urlencode "password=<password>"

PowerShell:

$body = @{ user = 'apiread'; password = '<password>' }
(Invoke-RestMethod -Method Post -Uri 'https://fw.example.com/api/?type=keygen' -Body $body -SkipCertificateCheck).response.result.key

Copy the returned <key> into PANOS_API_KEY. The same endpoint works against Panorama — point it at the Panorama hostname. Keys do not expire by default but are invalidated if the admin's password changes or the account is deleted.

Environment Variables

The raw escape hatches are off by default and gated twice: they register only when their PANOS_ENABLE_RAW_* flag is truthy and PANOS_MODE=admin, and even then an internal denylist blocks destructive verbs and protected config subtrees. See tools/_guards.py.

Install

Option A — uv (recommended). No install step: uvx fetches the package from PyPI on first run and caches it. Pin the version so upgrades are deliberate:

uvx node804-panos-mcp==0.1.6

Option B — pip:

pip install node804-panos-mcp

Option C — from source (development):

git clone https://github.com/Node804/node804-panos-mcp.git
cd node804-panos-mcp
uv sync          # or: pip install -e ".[dev]"

Each option provides the node804-panos-mcp command and the panos_mcp Python module (runnable as python -m panos_mcp). The package pulls in its dependency node804-mcp-toolkit — shared RBAC, audit-logging, TLS, and lean-response utilities — automatically.

Until node804-mcp-toolkit is published to PyPI, install it from source first: pip install git+https://github.com/Node804/node804-mcp-toolkit.git

Claude Desktop

1. Open your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

1. Add the server under mcpServers (create the file if it doesn't exist):

{
  "mcpServers": {
    "PAN-OS": {
      "command": "uvx",
      "args": ["node804-panos-mcp==0.1.6"],
      "env": {
        "PANOS_HOST": "fw.example.com",
        "PANOS_API_KEY": "LUFRPT1xxx...",
        "PANOS_MODE": "read"
      }
    }
  }
}

If you installed with pip instead of uv, use "command": "python" with "args": ["-m", "panos_mcp"].

1. Restart Claude Desktop — the server starts automatically when Claude needs it. It starts in read-only mode by default; raise PANOS_MODE to enable writes.

Claude Code (CLI)

claude mcp add node804-panos-mcp \
  -e PANOS_HOST=fw.example.com \
  -e PANOS_API_KEY=LUFRPT1xxx... \
  -e PANOS_MODE=read \
  -- uvx node804-panos-mcp==0.1.6

Verify with claude mcp list.

Verifying It Works

Once connected, ask your LLM:

• "What's my access level?" → calls server_status, showing the active mode, live tool counts, TLS posture, and configured firewalls
• "What firewalls are configured?" → calls list_firewalls, confirming the registry and which targets require an explicit firewall argument

If either fails, see Troubleshooting.

Token efficiency

Every list-returning tool accepts these parameters (from node804-mcp-toolkit):

Responses are wrapped as {total, count, items} so the LLM knows when pagination truncated the result and whether to fetch more. Single-record tools (get_firewall_info, get_ha_status, etc.) accept verbose and fields.

Measured savings

Token counts below were measured against synthetic fixtures sized to mid-range deployments (100 security rules, 500 address objects). Encoding: cl100k_base (GPT-4 / Claude approximation). Every scenario is a regression-guarded test in tests/benchmark/ — the build fails if a future change widens a response shape past the budget.

Run the benchmark suite yourself:

pytest -v -s -m benchmark

The headline number: a policy audit that would cost ~20K tokens via the naive "dump everything" approach costs ~60 tokens via `summarize_security_policy`.

Audit logging

Every tool invocation can be captured to a JSON-lines file:

export PANOS_AUDIT_LOG=/var/log/panos-mcp/audit.jsonl

Each line is one event:

{"ts":"2026-05-07T14:32:11.483Z","tool":"add_security_rule","mode":"full","firewall":"hq-fw","args":{"name":"block-tor","action":"deny"},"success":true,"duration_ms":412}

Sensitive keys (api_key, password, secret, token, auth) are redacted at any depth before logging. Strings over 2 KB are elided. Write failures warn once and never block tool execution.

The audit log is the only after-the-fact record for admin-mode operations (commit, set_config, run_op_command). Treat it accordingly.

TLS verification

Connections to PAN-OS are TLS-verified by default. For environments where the firewall presents a self-signed certificate or one signed by an internal CA:

# Option A: trust a custom CA bundle
export PANOS_TLS_CA=/etc/pki/internal-ca.pem

# Option B: disable verification (emits a startup warning)
export PANOS_TLS_VERIFY=false

The startup log reports the active posture:

PanOS TLS:   verify=ON (system trust store)
PanOS TLS:   verify=ON (custom CA via PANOS_TLS_CA)
PanOS TLS:   verify=OFF (PANOS_TLS_VERIFY=false)

Multi-firewall configuration

For environments managing multiple firewalls or Panorama instances, define them in ~/.config/panos-mcp/firewalls.json (override with PANOS_FIREWALLS_CONFIG=/path):

{
  "firewalls": [
    { "name": "hq",       "host": "hq.example.com" },
    { "name": "branch",   "host": "branch.example.com" },
    { "name": "panorama", "host": "panorama.example.com" }
  ]
}

API keys live in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service via keyring). On first run, plaintext api_key fields in older configs auto-migrate to the keychain and the JSON is rewritten without them.

Linux headless servers without a keychain backend fall back to plaintext storage. The file is written with mode 0o600 (owner read/write only). The startup log emits a warning.

In multi-firewall mode, every tool that talks to a firewall requires an explicit firewall: <name> argument — no default is picked. Call list_firewalls to see configured targets and whether firewall is required.

Tools by category

Each cell shows how many tools that category contributes at that RBAC tier. A — means none. The Total column sums across tiers; the bottom row matches the tool counts reported by server_status.

A few entries worth calling out by name:

• Diagnostics (read) — test_security_policy_match, test_nat_policy_match, test_routing_fib_lookup, get_sessions, get_session_detail. Live troubleshooting via read-only <test> and session ops.
• Utility — get_config_xpath, run_show_command, get_pending_changes, get_config_diff (read) for ad-hoc inspection and reviewing staged changes; run_op_command (admin) for the operational-command escape hatch.
• Aggregations (read) — includes get_rule_hit_counts and unused_rules for usage-based rule cleanup.
• Commit & raw API (admin) — commit, panorama_commit, panorama_push_to_devices, revert_config, set_config, delete_config.
• Server diagnostic — server_status and list_firewalls. Always available, even in read mode.

Call server_status from your MCP client at runtime to see the active mode, live tool counts, TLS posture, audit destination, and the configured firewall registry.

Aggregation tools

Purpose-built summarization tools that replace "dump everything and grep" patterns with focused queries. Returning a structured answer is 10-20x cheaper in tokens than returning the full inventory and letting the LLM compute the same thing — the largest single source of token savings in the project.

All are gated at Mode.READ — same tier as the underlying inventory reads.

Troubleshooting

Development

git clone https://github.com/Node804/node804-panos-mcp.git
cd node804-panos-mcp
pip install -e ".[dev]"          # or: uv sync --extra dev

pytest -v                                        # full test suite
pytest -v -m "not integration and not benchmark" # CI-equivalent
ruff check . && ruff format --check .            # lint + format
mypy src                                         # type check
node804-panos-mcp                                # boot the server

node804-mcp-toolkit installs automatically as a dependency. Until it's on PyPI, install it from source first (see Install).

Acknowledgments

Built on pan-os-python — Palo Alto Networks' official Python SDK. The PAN-OS object model and API client behavior come from there; this project provides the MCP wrapper, response shaping, RBAC, and audit infrastructure on top.

AI-Assisted Development

Portions of this project — including code, tests, and documentation — were developed with the assistance of generative AI (Anthropic's Claude, ChatGPT). All changes are human-reviewed before merge and exercised by the automated test suite, but as with any software, review the code and test against a non-production firewall or Panorama before trusting it with write access (standard mode or above) to a live device.

License

MIT