SonicWall NSM MCP Server

A read-only Model Context Protocol server for SonicWall Network Security Manager (NSM) SaaS. It gives any MCP-capable AI agent — Claude Code, Claude Desktop, Copilot Studio, or your own — 46 tools for answering real network-operations questions about a SonicWall firewall fleet:

"Is the Springfield site up?" · "Which firewalls still have IPS switched off?" · "What changed on this firewall in the last 24 hours?" · "Which site has the device with MAC 00:1A:2B...?" · "Is anything still permitting RDP inbound?"

Everything is read-only by construction: the HTTP client refuses non-GET methods before any I/O, and the recommended deployment authenticates with a MySonicWall account whose NSM role is ReadOnly — so a write is impossible even if the code were wrong.

Design principles

These rules are enforced across every tool, because they are what make an AI agent's answers trustworthy:

• "Zero findings" and "data unavailable" are never merged. Every response carries data_status: "ok" (zeros are real zeros) or "unavailable" (upstream failed — no data keys at all). Partial answers name each area that could not be read (areas_unavailable) and each area the platform cannot report at all (not_covered), so silence is never mistaken for health.

• Provenance is explicit. Every answer says whether it is live (read from the firewall right now), cached (NSM's tenant record, ≤60 s old), or collected (NSM's analytics store, only as fresh as the firewall's last check-in — where an offline firewall looks identical to a quiet one, the payload says so).

• Responses stay under 500 KB via field projection, top-N caps, and an explicit truncated flag with authoritative counts.

• Secrets never cross the boundary. Credential-dense payloads are projected through allow-lists of named fields (never deny-lists); config diffs return changed key names only, never values; registration/authentication codes are never returned.

• Chat-client-friendly schemas. Single primitive parameter types with defaults — no Optional[...] unions, which some MCP clients silently drop.

Related MCP server: Datadog MCP Server

Tools

Fleet posture (cached from NSM's tenant record, ≤60 s old)

Per-site live reads (read from the firewall on demand)

Fleet-wide sweep-backed search (background sweep, one GET per device)

Change management (NSM manager plane)

Telemetry & analytics (collected by NSM)

Fleet security services (one tenant-wide call)

A diagnostic _debug_slow tool (for measuring client timeout budgets) is registered only when MCP_DEBUG_TOOLS=1.

Requirements

• Python 3.12+

• A SonicWall NSM SaaS tenant (this server talks to the NSM cloud API, not directly to SonicOS on-box APIs)

• A MySonicWall API key — ideally from a dedicated account whose NSM role is ReadOnly

Quick start (local)

git clone <this repo>
cd sonicwall-nsm-mcp
python -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r requirements.txt -c constraints.txt

Provide the API key one of two ways:

# Option A: environment variable
export MSW_API_KEY_READONLY="<your MySonicWall API key>"

# Option B: OS keyring (Windows Credential Manager / macOS Keychain / libsecret)
python -c "import keyring,getpass; keyring.set_password('msw-api-key-readonly','<your-msw-login>',getpass.getpass('key: '))"

Verify the credential and auth chain end to end (also confirms the effective NSM role, so you know the key really is read-only):

python nsm_auth.py

Run the server:

export MCP_INBOUND_API_KEY="<generate a long random string>"
python server.py           # serves streamable HTTP MCP on :8080, GET /health for liveness

Attach it to Claude Code:

claude mcp add sonicwall-nsm --transport http http://localhost:8080/mcp \
  --header "X-API-Key: <your MCP_INBOUND_API_KEY>"

Any other MCP client works the same way: streamable HTTP transport, X-API-Key header.

Configuration (environment variables)

Tenant discovery: with MSW_TENANT_ID/NSM_TENANT_SERIAL unset, the server discovers them from the MySonicWall get-cloud-tenants API at first use. If your account sees exactly one tenant, nothing more is needed; otherwise set MSW_TENANT_NAME (or the explicit IDs, which python nsm_auth.py prints via discover_tenant_ids).

Docker

docker build -t sonicwall-nsm-mcp .
docker run -p 8080:8080 \
  -e MSW_API_KEY_READONLY="..." \
  -e MCP_INBOUND_API_KEY="..." \
  sonicwall-nsm-mcp

The container logs one structured JSON line per tool call to stdout.

Security model

• Read-only, twice over. NsmSession raises on any non-GET/HEAD/OPTIONS method before any I/O; and if you provision the recommended ReadOnly MySonicWall account, NSM itself will refuse writes regardless of what any code asks for. Verify the effective role with python nsm_auth.py.

• Inbound auth is fail-closed. With MCP_INBOUND_API_KEY unset, every request except /health is rejected. The key is compared constant-time.

• Secret projection. Live status reads use allow-lists (registration and authentication codes are never projected); config diffs emit changed key names only; SNMP community strings, PSKs, password hashes and RADIUS/LDAP secrets are never read out of any payload.

• Personal data is labelled. SSL-VPN session lists and per-user traffic tables carry an explicit contains_personal_data / privacy_note flag so your agent layer can gate them.

Operational notes

• The background sweep makes one GET per online device per cycle (default every 30 min) for the three fleet-search tools. Disable with SWEEP_ENABLED=0 if you don't need them; those tools then report data_status: "unavailable" honestly.

• NSM bearer tokens have a 15-minute inactivity timeout; the session re-runs the auth chain automatically.

• Several NSM endpoints answer HTTP 200 with an error body; the server detects that and reports "unavailable" rather than presenting an answer-shaped non-answer. Many hard-won API behaviors (boolean limit gates, CSV-in-JSON payloads, integer-encoded IPs, misspelled vendor fields) are documented in comments where they are handled.

License

MIT — see LICENSE.