@teamnetwork-nz/sonicwall-api-mcp-server 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +141 -0
  2. package/bin/index.js +63 -0
  3. package/package.json +39 -0
package/README.md ADDED
@@ -0,0 +1,141 @@
1
+ # SonicWall NSA MCP Server
2
+
3
+ A [Model Context Protocol](https://modelcontextprotocol.io/) server that provides full read/write access to SonicWall NSA series appliances via the SonicOS REST API.
4
+
5
+ ## Features
6
+
7
+ - **Log analysis** — retrieve, filter, and search event logs, traffic logs, and threat/IPS events
8
+ - **Address objects & groups** — CRUD for IPv4, IPv6, FQDN, and MAC address objects and their groups
9
+ - **Service objects & groups** — CRUD for protocol/port service definitions
10
+ - **Access rules** — create, update, enable/disable, and delete firewall access rules (IPv4 & IPv6)
11
+ - **NAT policies** — full CRUD for inbound/outbound NAT rules
12
+ - **Security policies** — CRUD for zone-based security policies
13
+ - **GeoIP filtering** — manage GeoIP country-block policies and assign them to access rules
14
+ - **Config management** — view and commit (or discard) staged changes
15
+
16
+ Supports SonicOS 6.5.x, 7.x, and 8.x with automatic version detection.
17
+
18
+ ## Quick Start
19
+
20
+ ### Install
21
+
22
+ **Via npm / npx (recommended — no Python setup required):**
23
+
24
+ ```bash
25
+ # Run directly with npx (requires uv: https://docs.astral.sh/uv/)
26
+ npx @teamnetwork-nz/sonicwall-api-mcp-server
27
+
28
+ # Or install globally
29
+ npm install -g @teamnetwork-nz/sonicwall-api-mcp-server
30
+ sonicwall-mcp
31
+ ```
32
+
33
+ **Via pip / uv (Python):**
34
+
35
+ ```bash
36
+ pip install sonicwall-mcp-server
37
+ # or:
38
+ uv pip install sonicwall-mcp-server
39
+ ```
40
+
41
+ > **Note:** The npm package is a thin launcher. It requires [uv](https://docs.astral.sh/uv/) to be installed and uses `uvx sonicwall-mcp-server` under the hood. No Python environment setup is needed beyond installing uv.
42
+
43
+ ### Configure
44
+
45
+ Pass credentials as environment variables (no config file needed):
46
+
47
+ ```bash
48
+ SONICWALL_HOST=192.168.168.168
49
+ SONICWALL_USERNAME=admin
50
+ SONICWALL_PASSWORD=your_password
51
+ SONICWALL_SSL_VERIFY=false # most appliances use self-signed certs
52
+ ```
53
+
54
+ Copy `.env.example` to `.env` for local development.
55
+
56
+ ### Claude Desktop / Claude Code Integration
57
+
58
+ Add to your MCP config (`claude_desktop_config.json` or `.claude/settings.json`):
59
+
60
+ **Using npx (easiest):**
61
+
62
+ ```json
63
+ {
64
+ "mcpServers": {
65
+ "sonicwall": {
66
+ "command": "npx",
67
+ "args": ["-y", "@teamnetwork-nz/sonicwall-api-mcp-server"],
68
+ "env": {
69
+ "SONICWALL_HOST": "192.168.168.168",
70
+ "SONICWALL_USERNAME": "admin",
71
+ "SONICWALL_PASSWORD": "your_password",
72
+ "SONICWALL_SSL_VERIFY": "false"
73
+ }
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ **Using uvx directly:**
80
+
81
+ ```json
82
+ {
83
+ "mcpServers": {
84
+ "sonicwall": {
85
+ "command": "uvx",
86
+ "args": ["sonicwall-mcp-server"],
87
+ "env": {
88
+ "SONICWALL_HOST": "192.168.168.168",
89
+ "SONICWALL_USERNAME": "admin",
90
+ "SONICWALL_PASSWORD": "your_password",
91
+ "SONICWALL_SSL_VERIFY": "false"
92
+ }
93
+ }
94
+ }
95
+ }
96
+ ```
97
+
98
+ **Using the installed Python CLI:**
99
+
100
+ ```json
101
+ {
102
+ "mcpServers": {
103
+ "sonicwall": {
104
+ "command": "sonicwall-mcp",
105
+ "env": {
106
+ "SONICWALL_HOST": "192.168.168.168",
107
+ "SONICWALL_USERNAME": "admin",
108
+ "SONICWALL_PASSWORD": "your_password",
109
+ "SONICWALL_SSL_VERIFY": "false"
110
+ }
111
+ }
112
+ }
113
+ }
114
+ ```
115
+
116
+ ### Development
117
+
118
+ ```bash
119
+ uv venv && source .venv/bin/activate
120
+ uv pip install -e ".[dev]"
121
+ pytest tests/ -v # unit tests (no appliance needed)
122
+ mcp dev src/sonicwall_mcp/server.py # interactive MCP inspector
123
+ ```
124
+
125
+ ## Agent guidance
126
+
127
+ The server supplies MCP `instructions` that are automatically delivered to the calling agent at session start. These cover:
128
+
129
+ - **Staged configuration** — always `commit_config` after a related set of changes, or `discard_config` to abandon
130
+ - **Datetime handling** — log timestamps use the appliance's local timezone; no UTC conversion needed
131
+ - **Log tool selection** — when to use `get_event_logs` vs `get_traffic_logs` vs `get_threat_logs` vs `search_logs`
132
+ - **Object and rule management** — recommended workflow for creating address objects and firewall rules
133
+ - **Concurrent sessions** — SonicOS limit of one active API session per appliance
134
+
135
+ No special prompting is required — the agent receives these guidelines automatically.
136
+
137
+ ## Important Notes
138
+
139
+ - SonicOS allows only **one concurrent API session** per appliance. Ensure no other admin sessions are active when using this server.
140
+ - All configuration changes (create/update/delete) are **staged** and do not take effect until you call `commit_config`. Use `discard_config` to abandon staged changes.
141
+ - Enable the SonicOS API in the appliance web UI: **DEVICE > Settings > Administration > SonicOS API**.
package/bin/index.js ADDED
@@ -0,0 +1,63 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Launcher for the SonicWall MCP server (Python package).
4
+ * Requires uv to be installed: https://docs.astral.sh/uv/
5
+ *
6
+ * Usage:
7
+ * npx @teamnetwork-nz/sonicwall-api-mcp-server
8
+ *
9
+ * Environment variables:
10
+ * SONICWALL_HOST, SONICWALL_USERNAME, SONICWALL_PASSWORD (required)
11
+ * SONICWALL_SSL_VERIFY, SONICWALL_READ_ONLY, ... (optional — see .env.example)
12
+ */
13
+
14
+ const { spawn } = require('child_process');
15
+
16
+ const args = process.argv.slice(2);
17
+ const isWindows = process.platform === 'win32';
18
+
19
+ function run(cmd, cmdArgs) {
20
+ return spawn(cmd, cmdArgs, {
21
+ stdio: 'inherit',
22
+ env: process.env,
23
+ shell: isWindows,
24
+ });
25
+ }
26
+
27
+ function startWithFallback() {
28
+ const proc = run('uvx', ['sonicwall-mcp-server@latest', ...args]);
29
+
30
+ proc.on('error', (err) => {
31
+ if (err.code !== 'ENOENT') {
32
+ console.error(`sonicwall-mcp: failed to start via uvx: ${err.message}`);
33
+ process.exit(1);
34
+ }
35
+
36
+ // uvx not available — try python -m fallback
37
+ console.error(
38
+ 'sonicwall-mcp: uvx not found. Falling back to `python -m sonicwall_mcp.server`.\n' +
39
+ 'Install uv for the best experience: https://docs.astral.sh/uv/'
40
+ );
41
+
42
+ const fallback = run('python', ['-m', 'sonicwall_mcp.server', ...args]);
43
+
44
+ fallback.on('error', (e) => {
45
+ if (e.code === 'ENOENT') {
46
+ console.error(
47
+ 'sonicwall-mcp: neither uvx nor python was found.\n' +
48
+ 'Install uv (https://docs.astral.sh/uv/) or Python with sonicwall-mcp-server:\n' +
49
+ ' pip install sonicwall-mcp-server'
50
+ );
51
+ } else {
52
+ console.error(`sonicwall-mcp: ${e.message}`);
53
+ }
54
+ process.exit(1);
55
+ });
56
+
57
+ fallback.on('close', (code) => process.exit(code ?? 0));
58
+ });
59
+
60
+ proc.on('close', (code) => process.exit(code ?? 0));
61
+ }
62
+
63
+ startWithFallback();
package/package.json ADDED
@@ -0,0 +1,39 @@
1
+ {
2
+ "name": "@teamnetwork-nz/sonicwall-api-mcp-server",
3
+ "version": "0.2.0",
4
+ "description": "MCP server for SonicWall NSA appliance API — logs, CRUD objects, rules, NAT, GeoIP",
5
+ "keywords": [
6
+ "mcp",
7
+ "model-context-protocol",
8
+ "sonicwall",
9
+ "firewall",
10
+ "sonicOS",
11
+ "api",
12
+ "network",
13
+ "security"
14
+ ],
15
+ "homepage": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server",
16
+ "bugs": {
17
+ "url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server/issues"
18
+ },
19
+ "license": "MIT",
20
+ "author": "Daryl",
21
+ "bin": {
22
+ "sonicwall-mcp": "./bin/index.js"
23
+ },
24
+ "files": [
25
+ "bin/",
26
+ "README.md",
27
+ "LICENSE"
28
+ ],
29
+ "scripts": {
30
+ "start": "node bin/index.js"
31
+ },
32
+ "engines": {
33
+ "node": ">=18"
34
+ },
35
+ "repository": {
36
+ "type": "git",
37
+ "url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server.git"
38
+ }
39
+ }