Sophos Firewall MCP Server
by jelmervdm
README.md
# Sophos Firewall MCP Server (`sophos-firewall-mcp`)
[](https://github.com/jelmervdm/sophos-firewall-mcp)
[](LICENSE)
[](pyproject.toml)
[-success.svg)](https://github.com/glama-ai/tool-definition-quality-score)
An asynchronous [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for Sophos Firewall (SFOS), enabling AI assistants (such as Antigravity IDE, Claude Desktop, VS Code, and Cursor) to manage, audit, and troubleshoot Sophos Firewall network security infrastructure.
---
## 🌟 Key Features
* **Async XML API Integration:** Built on `httpx.AsyncClient` for high-throughput, non-blocking IO with Sophos SFOS XML API endpoints (`/webconsole/APIController`).
* **7 Comprehensive Tool Domains (28 Tools):**
* **System & Status:** System version, serial number, uptime, service operational state, and network interface configurations.
* **Firewall Rules:** Security policies listing, creation, status toggling, and rule deletion.
* **Host & Network Objects:** IP host definitions, network subnets, IP host groups, and FQDN objects.
* **Services:** Custom TCP/UDP service objects, port ranges, and service groups.
* **NAT Rules:** SNAT and DNAT port-forwarding rule inspection.
* **User Management:** Local user account configuration and live user session monitoring.
* **VPN Management:** IPsec site-to-site tunnels and SSL VPN remote access policies.
* **FastMCP Resources:** Read-only system state via URIs (`sophos://system/info`, `sophos://interfaces`, `sophos://services/status`).
* **Guided Prompts:** Contextual security audits (`audit_firewall_rules`) and traffic troubleshooting (`troubleshoot_connectivity`).
* **Semantic Tool Router:** FastEmbed text embedding router for intelligent tool selection (`USE_ROUTER=true`).
* **Tier A+ Quality Score:** 100% parameter descriptions, full `ToolAnnotations` safety metadata, and 100% test coverage.
---
## 🏆 Tool Definition Quality Score (TDQS)
This server is audited against the **[Tool Definition Quality Score (TDQS)](https://github.com/glama-ai/tool-definition-quality-score)** framework to guarantee optimal function calling, type safety, and runtime safety for LLMs.
```text
---------------- SCORECARD METRICS ----------------
Tools Evaluated : 39
Behavioral Annotations : 39 / 39 (100.0%)
100% Parameter Descriptions : 39 / 39 (100.0%)
Usage Guidelines (Docstrings): 39 / 39 (100.0%)
Overall TDQS Score : 5.00 / 5.00
TDQS Quality Tier : Tier A+
========================================================
```
- **Behavioral Annotations (`ToolAnnotations`):** 100% of tools specify `readOnlyHint`, `destructiveHint`, and `idempotentHint` metadata.
- **Parameter Descriptions (`Annotated[..., Field(...)]`):** Every parameter includes explicit typing and human-readable descriptions.
- **Usage Guidelines:** Standardized docstrings detailing exact trigger conditions ("Use when...").
---
## ⚙️ Sophos Firewall API Prerequisites
Before connecting `sophos-firewall-mcp` to your Sophos Firewall (SFOS) appliance, ensure the XML API is enabled and your client IP is whitelisted:
1. **Log in to Web Admin Console**: Open `https://<SOPHOS_HOST>:4444` in your browser.
2. **Enable API Access**:
- Navigate to **System** > **Administration** > **API Access** (or **API Configuration**).
- Check the **API Configuration** toggle/checkbox to enable the API service.
3. **Whitelist Client IP Address**:
- Under **Allowed IP Addresses**, click **Add** and specify the IP address of the machine or container host running `sophos-firewall-mcp`.
- *Note*: Sophos Firewall rejects API requests from any IP address not explicitly added to this whitelist.
4. **Administrator Account**:
- Ensure the configured user account (`SOPHOS_USERNAME`) has active administrator privileges.
---
## 🔧 Environment Variables
| Variable | Description | Default |
| :--- | :--- | :--- |
| `SOPHOS_HOST` | Sophos Firewall IP address or FQDN | `172.16.16.16` |
| `SOPHOS_PORT` | Web Console API port | `4444` |
| `SOPHOS_USERNAME` | API Administrator Username | `admin` |
| `SOPHOS_PASSWORD` | API Administrator Password | *(Required)* |
| `SOPHOS_API_VERSION` | Sophos XML API Version (e.g., `2200.1` for SFOS v22) | `2200.1` |
| `SOPHOS_VERIFY_SSL` | Verify SSL/TLS certificates (set `false` for self-signed certs) | `false` |
| `SOPHOS_TIMEOUT` | API request timeout in seconds | `30.0` |
| `USE_ROUTER` | Set `true` to enable FastEmbed semantic tool routing | `false` |
---
## 🛠 Client Integration
Add the configuration snippet matching your environment to your MCP settings file (e.g. `.vscode/mcp.json` or `mcp_config.json` in Antigravity IDE, Claude Desktop, or VS Code).
### Option 1: Docker / Podman Drop-in Container Deployment
Podman is fully supported as a rootless drop-in replacement for Docker on Fedora/RHEL/Linux:
```json
{
"mcpServers": {
"sophos-firewall": {
"command": "podman",
"args": [
"run",
"-i",
"--rm",
"--pull=newer",
"-e", "SOPHOS_HOST",
"-e", "SOPHOS_PORT",
"-e", "SOPHOS_USERNAME",
"-e", "SOPHOS_PASSWORD",
"-e", "SOPHOS_API_VERSION",
"-e", "SOPHOS_VERIFY_SSL",
"-e", "USE_ROUTER",
"ghcr.io/jelmervdm/sophos-firewall-mcp:latest"
],
"env": {
"SOPHOS_HOST": "172.16.16.16",
"SOPHOS_PORT": "4444",
"SOPHOS_USERNAME": "admin",
"SOPHOS_PASSWORD": "your_secure_password_here",
"SOPHOS_API_VERSION": "2200.1",
"SOPHOS_VERIFY_SSL": "false",
"USE_ROUTER": "false"
}
}
}
}
```
> **Tip for Docker vs Podman**: Replace `"command": "podman"` with `"command": "docker"` if using standard Docker. Ensure `-i` is retained and **never** use `-t` (TTY mode), as TTY mode injects carriage returns (`\r\n`) that disrupt stdio JSON-RPC protocol parsing.
---
### Option 2: Local Python Execution (without PyPI)
#### Via `uv` (Local Workspace Directory):
```json
{
"mcpServers": {
"sophos-firewall": {
"command": "uv",
"args": [
"--directory",
"/path/to/sophos-firewall-mcp",
"run",
"sophos-firewall-mcp-server"
],
"env": {
"SOPHOS_HOST": "172.16.16.16",
"SOPHOS_PORT": "4444",
"SOPHOS_USERNAME": "admin",
"SOPHOS_PASSWORD": "your_secure_password_here",
"SOPHOS_VERIFY_SSL": "false"
}
}
}
}
```
#### Via `python` (Editable Install `pip install -e .`):
```json
{
"mcpServers": {
"sophos-firewall": {
"command": "python",
"args": ["-m", "sophos_firewall_mcp.server"],
"env": {
"SOPHOS_HOST": "172.16.16.16",
"SOPHOS_PORT": "4444",
"SOPHOS_USERNAME": "admin",
"SOPHOS_PASSWORD": "your_secure_password_here",
"SOPHOS_VERIFY_SSL": "false"
}
}
}
}
```
#### Via `uvx` directly from GitHub Repository:
```json
{
"mcpServers": {
"sophos-firewall": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/jelmervdm/sophos-firewall-mcp.git",
"sophos-firewall-mcp-server"
],
"env": {
"SOPHOS_HOST": "172.16.16.16",
"SOPHOS_PORT": "4444",
"SOPHOS_USERNAME": "admin",
"SOPHOS_PASSWORD": "your_secure_password_here",
"SOPHOS_VERIFY_SSL": "false"
}
}
}
}
```
---
## 🧠 Semantic Tool Routing
When connecting `sophos-firewall-mcp` to AI models with constrained context windows, set `USE_ROUTER=true` (or `TOOL_ROUTING=true`).
When enabled:
1. The server exposes only 2 meta-tools: `route_tools` and `call_routed_tool`.
2. `route_tools` uses local CPU embeddings (`fastembed` with `BAAI/bge-small-en-v1.5`) to search for matching firewall tools in 5-10ms.
3. `call_routed_tool` dynamically invokes the matching tool with parameters.
> **Note on Router Dependencies**: Semantic routing requires optional dependencies (`fastembed` and `numpy`).
> - **Container (Docker/Podman)**: Included automatically in official images (`ghcr.io/jelmervdm/sophos-firewall-mcp:latest`).
> - **Local Python (`pip`)**: Install with extras: `pip install -e ".[router]"` or `pip install "sophos-firewall-mcp-server[router]"`.
> - **`uv` Workspace**: Run `uv sync --extra router`.
> - **`uvx` directly from Git**: Pass `--with "fastembed>=0.4.0" --with "numpy>=1.26.0"`.
> If `USE_ROUTER=true` is set without installing `fastembed`, the server will log a warning and gracefully fall back to standard tool mode instead of failing initialization.
---
## 🧪 Testing & Quality Assurance
Run the comprehensive test suite, linting, mypy type checks, and TDQS audit:
```bash
# Evaluate Tool Definition Quality Score (TDQS)
uv run python scripts/check_tdqs.py
# Run pytest unit test suite (39 tests)
uv run pytest -v
# Code style and syntax linting
uv run flake8 src tests scripts
# Static type verification
uv run mypy src
```
---
## 📄 License
Distributed under the Apache 2.0 License. See [LICENSE](LICENSE) for details.
TDQS
A3.9/5.0
Scored across 41 tools
Disambiguation5/5
Each tool addresses a distinct resource and action (e.g., list, get, create, update, delete) with clear separation. Potential overlaps like list vs get firewall rules are resolved by naming and description. No two tools could be easily confused.
Naming Consistency5/5
All tools follow a consistent 'sophos_<action>_<resource>' snake_case pattern. The two routing tools deviate slightly but are justified by their different role. Overall, naming is predictable and uniform.
Tool Count4/5
41 tools is large but the Sophos Firewall domain covers many resources (firewall rules, hosts, services, NAT, VPN, users, etc.) with full CRUD on most. The count is high but each tool serves a distinct purpose; a few could potentially be consolidated.
Completeness3/5
Major resources like firewall rules, NAT, and users have good lifecycle coverage, but IP hosts, FQDN hosts, services, groups, and VPNs lack update operations. This forces agents to delete and recreate for modifications, which is a notable gap.
Maintenance
ActivityActive
ResponsivenessNo issues