PAN-OS MCP server

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.

PanOS Engineer Skill

The repo also ships a skill, skills/panos-engineer/SKILL.md, that teaches the model how to work with PAN-OS and Panorama through these tools: which summary/count tool to reach for before dumping an inventory, how firewall-vs-Panorama targeting and the redirect guards work, policy/NAT/decryption audit patterns, and connectivity, routing, and VPN troubleshooting. The server works without it, but the model makes fewer calls and fewer mistakes with it.

Permission Modes

Mode	Tools	Description
read (default)	89	Read-only inspection, live troubleshooting (policy-match / NAT-match / FIB-lookup tests, session table, config diff, rule hit counts), and aggregation summaries. No writes.
standard	99	Read + object and tag CRUD (address objects, service objects, tags). No policy rules.
full	130	Standard + policy rule CRUD (security, NAT, PBF, QoS, decryption, static routes; Panorama pre/post rules). All writes go to candidate config — no live impact without commit.
admin	137	Full + commit, push, revert_config, and the raw set_config / delete_config / run_op_command escape hatches. This is the live-impact tier.

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 (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.

Custom (role-based) admin accounts: if the key belongs to a custom admin role rather than a dynamic Superuser role, check the role's Privacy settings (Admin Role Profile → Web UI tab → Privacy). When Show Full IP Addresses is disabled, PAN-OS masks source and destination IPs to their /24 network in every log and report — including the data served over the XML API — so the MCP will return e.g. 172.28.31.0/24 instead of the host address. Enable Show Full IP Addresses (and Show User Names In Logs And Reports for usernames), then commit. On a Panorama-authenticated key this is a Panorama admin role, so a Panorama commit applies it — no device push needed. This masking is applied by PAN-OS, not the MCP; the server passes the API's values through unchanged.

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

Variable	Required	Description
PANOS_HOST	Yes*	Single-firewall hostname. *Not required in multi-firewall mode (see Multi-firewall configuration).
PANOS_API_KEY	Yes*	Single-firewall API key. Stored in the OS keychain in multi-firewall mode.
PANOS_MODE	No	RBAC mode: read, standard, full, or admin. Default: read.
PANOS_TLS_VERIFY	No	true / false / 1 / 0 / yes / no. Default: true.
PANOS_TLS_CA	No	Path to a custom PEM CA bundle. Default: system trust store.
PANOS_FIREWALLS_CONFIG	No	Override path for firewalls.json. Default: ~/.config/panos-mcp/firewalls.json.
PANOS_ALLOW_SERIAL_CONNECTION	No	true / false (default false). When on and the configured connection is a Panorama, reach any managed firewall by serial through Panorama — one key for the whole fleet. See Serial-through-Panorama.
PANOS_AUDIT_LOG	No	Path to a JSON-lines audit log. Every tool call is logged with sanitized args, success/error state, and timing. Disabled when unset.
PANOS_ENABLE_RAW_CONFIG	No	Register set_config / delete_config (also requires PANOS_MODE=admin). Default: false.
PANOS_ENABLE_RAW_OPS	No	Register run_op_command (also requires PANOS_MODE=admin). Default: false.
PANOS_RAW_XPATH_ALLOW	No	Comma-separated XPath prefixes that set_config / delete_config are restricted to. Default: unset (all non-denied).

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.2.0

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

Quick setup (wizard)

After a pip install, the fastest way to get configured is the bundled wizard:

node804-panos-mcp-setup

If node804-panos-mcp-setup isn't found, the console script isn't on your PATH (common with a pip --user install or a venv that isn't active). Use the module form instead — it's identical and works for every subcommand below:

python -m panos_mcp.setup

Use the full interpreter path if python isn't the one you installed into, e.g. C:\Python313\python.exe -m panos_mcp.setup.

It walks through, in order:

1. a firewalls.json entry (name + host) at ~/.config/panos-mcp/firewalls.json;
2. your API key, stored in the OS keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service) — never written to disk in plaintext;
3. an interactive prompt to wire up Claude Desktop (backs up the config first; writes a server entry with no host or key in it — both resolve from steps 1–2); and
4. installing the panos-engineer skill — copied into ~/.claude/skills for Claude Code, and zipped for upload to Claude Desktop / claude.ai.

Each AI client is a separate yes/no question, so you can set up only what you use. Non-interactive install (e.g. for scripted rollout):

PANOS_SETUP_API_KEY=LUFRPT1xxx... node804-panos-mcp-setup \
  --name panorama --host panorama.example.com --mode read \
  --serial --claude --skill --yes

Run node804-panos-mcp-setup --help (or python -m panos_mcp.setup --help) for every flag. The manual equivalents are documented in the client sections below.

The wizard is modify-aware: when firewalls.json already has entries it lists them and lets you skip straight to the client/skill steps, so re-running it never forces you to re-enter a firewall. It also exposes subcommands for day-to-day changes:

# Upgrade just the skill (after pip install -U node804-panos-mcp)
node804-panos-mcp-setup skill

# Manage firewalls.json without the full wizard
node804-panos-mcp-setup firewall list
node804-panos-mcp-setup firewall add --name branch --host branch.example.com
node804-panos-mcp-setup firewall remove --name branch

firewall add with an existing name updates that entry (keeping the stored key unless you change it); firewall remove deletes both the entry and its keychain key.

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

   Or open it from Claude Desktop: Settings → Developer → Edit Config.

2. Add a PAN-OS entry under mcpServers (create the file if it doesn't exist), using one of the options below. Every value in env must be a string.

3. 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.

Option A — uvx (recommended). Nothing to install beyond uv. The package is fetched from PyPI on first launch and cached; change the pinned version to upgrade.

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

Claude Desktop does not always inherit your shell's PATH. If it reports that uvx can't be found, use the full path to the executable: run where uvx (Windows) or which uvx (macOS) and put the result in command, e.g. "C:\\Users\\you\\.local\\bin\\uvx.exe" or "/Users/you/.local/bin/uvx".

Option B — pip. Install the package first, then point Claude Desktop at the Python interpreter you installed it into:

pip install node804-panos-mcp==0.2.0

{
  "mcpServers": {
    "PAN-OS": {
      "command": "python",
      "args": ["-m", "panos_mcp"],
      "env": {
        "PANOS_HOST": "fw.example.com",
        "PANOS_API_KEY": "LUFRPT1xxx...",
        "PANOS_MODE": "read"
      }
    }
  }
}

Use the full path to the interpreter if python on Claude Desktop's PATH isn't the one that has the package (common with virtual environments, the Windows Store Python, or multiple installs). Find it with python -c "import sys; print(sys.executable)". Alternatively, set "command" to the full path of the node804-panos-mcp script pip installed (in the interpreter's Scripts\ folder on Windows or bin/ on macOS) and drop args.

To upgrade a pip install: pip install -U node804-panos-mcp, then restart Claude Desktop.

Install the skill. Zip the panos-engineer folder (the zip must contain panos-engineer/SKILL.md) and upload it under Settings → Capabilities → Skills (skills must be enabled for your plan or organization):

Compress-Archive -Path skills\panos-engineer -DestinationPath panos-engineer-skill.zip

After upgrading the server, update the skill too — it describes tool behavior for the matching version.

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.2.0

Verify with claude mcp list.

Install the skill. Copy the panos-engineer folder into your personal skills directory — or into .claude/skills/ inside a project to scope it there:

mkdir -p ~/.claude/skills && cp -r skills/panos-engineer ~/.claude/skills/

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse skills\panos-engineer "$env:USERPROFILE\.claude\skills\"

ChatGPT

ChatGPT desktop app (recommended). The desktop app can launch local stdio servers directly, the same way Claude Desktop does. Open the app's Connect to a custom MCP form (Developer mode / custom connectors in settings) and fill it in:

Field	Value
Name	PAN-OS
Type	STDIO
Command to launch	uvx (or the full path from where uvx / which uvx if the app can't find it)
Arguments	node804-panos-mcp==0.2.0
Environment variables	PANOS_HOST, PANOS_API_KEY, PANOS_MODE, plus any optional ones from Environment Variables

For a pip install, set Command to launch to the full path of your Python interpreter and add two arguments: -m and panos_mcp. Put each argument in its own box (+ Add argument), not space-separated in one.

If the variables are already set in your user environment, you can list their names under Environment variable passthrough instead of typing the values into the form.

ChatGPT on the web. chatgpt.com can only reach remote MCP servers over HTTPS, so it cannot launch this stdio server. You'd need a stdio-to-HTTP bridge such as mcp-proxy plus a public HTTPS tunnel. That bridge has no authentication: anyone who learns the URL can use every tool in your mode with your PAN-OS API key — and the default read mode still exposes your entire firewall configuration and logs. Use the desktop app instead unless you can put real authentication (e.g. Cloudflare Access) in front of it, and keep it in read mode.

OpenAI Codex (CLI / IDE extension) does support local stdio servers, so no bridge is needed:

codex mcp add panos \
  --env PANOS_HOST=fw.example.com \
  --env PANOS_API_KEY=LUFRPT1xxx... \
  --env PANOS_MODE=read \
  -- uvx node804-panos-mcp==0.2.0

Or add it to ~/.codex/config.toml by hand:

[mcp_servers.panos]
command = "uvx"
args = ["node804-panos-mcp==0.2.0"]

[mcp_servers.panos.env]
PANOS_HOST = "fw.example.com"
PANOS_API_KEY = "LUFRPT1xxx..."
PANOS_MODE = "read"

Install the skill. Codex reads skills from ~/.codex/skills/, so copy the panos-engineer folder there. In the ChatGPT app, paste the body of SKILL.md (everything below the --- front matter) into a Project's instructions or your custom instructions.

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):

Parameter	Default	Effect
verbose	false	When true, returns every field the underlying API exposes. Default returns only the fields most relevant to the tool's purpose.
fields	null	Explicit projection. ["name", "action", "disabled"] returns exactly those fields. Overrides both verbose and the default whitelist.
pagination.limit	100	Max items per response. Hard ceiling: 1000.
pagination.offset	0	Skip count. Use with limit to page through inventories.
pattern	null	Server-side substring filter on the item's name field. Far cheaper than fetching the inventory and filtering client-side.

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.

Scenario	Naive approach	Tokens	Better approach	Tokens	Saving
Find an address object by IP	get_address_objects (dump 500)	21,207	find_address_object("10.0.0.5")	88	241× smaller
Inventory snapshot	get_address_objects (dump 500)	21,207	count_objects_by_type	27	785× smaller
Audit security policy	get_security_rules (verbose, 100 rules)	19,627	summarize_security_policy	58	338× smaller
Audit security policy	get_security_rules (lean, 100 rules)	5,095	summarize_security_policy	58	88× smaller
Find rules matching a pattern	get_security_rules (lean dump)	5,095	find_rule_by_name("rule-001")	249	20× smaller
Filter rules by pattern	get_security_rules (no filter)	5,095	get_security_rules(pattern="rule-00")	523	10× smaller
Lean default vs verbose	get_security_rules(verbose=true)	19,627	get_security_rules (default)	5,095	74% reduction

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.