mcp-pfsense 0.1.0__tar.gz

mcp_pfsense-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Type check
+        run: mypy src/
+
+      - name: Test
+        run: pytest -v

mcp_pfsense-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.env
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

mcp_pfsense-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Mello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_pfsense-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: mcp-pfsense
+Version: 0.1.0
+Summary: MCP server for managing pfSense firewalls through AI assistants
+Project-URL: Homepage, https://github.com/antonio-mello-ai/mcp-pfsense
+Project-URL: Repository, https://github.com/antonio-mello-ai/mcp-pfsense
+Project-URL: Issues, https://github.com/antonio-mello-ai/mcp-pfsense/issues
+Author-email: Antonio Mello <antonio.mello@felhen.com.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,firewall,infrastructure,llm,mcp,pfsense,server
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking :: Firewalls
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-pfsense
+
+[![PyPI](https://img.shields.io/pypi/v/mcp-pfsense)](https://pypi.org/project/mcp-pfsense/)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-pfsense)](https://pypi.org/project/mcp-pfsense/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for managing **pfSense firewalls** through AI assistants like Claude, ChatGPT, and Copilot.
+
+> **Requires**: [pfrest](https://github.com/pfrest/pfSense-pkg-RESTAPI) package installed on your pfSense instance (provides the REST API).
+
+## Features
+
+**17 tools** across 6 categories:
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **System** | `get_system_status`, `get_interfaces` | Version, CPU, memory, uptime, temperature, network interfaces |
+| **Firewall** | `list_firewall_rules`, `add_firewall_rule`, `delete_firewall_rule`, `list_firewall_aliases` | Rule management with interface filtering, alias listing |
+| **DHCP** | `list_dhcp_leases`, `list_dhcp_static_mappings`, `add_dhcp_static_mapping`, `delete_dhcp_static_mapping` | Active leases, IP reservations |
+| **DNS** | `list_dns_host_overrides`, `add_dns_host_override`, `delete_dns_host_override` | Unbound DNS Resolver host overrides |
+| **Monitoring** | `get_gateway_status`, `get_arp_table`, `list_services` | Gateway health, connected devices, service status |
+| **Services** | `restart_service` | Restart any pfSense service |
+
+### Safety
+
+All destructive operations (delete rules, delete mappings, restart services) require **two-step confirmation** — the tool returns a warning on first call and only executes when called again with `confirm=true`.
+
+## Installation
+
+```bash
+# Using uvx (recommended)
+uvx mcp-pfsense
+
+# Using pip
+pip install mcp-pfsense
+```
+
+### Prerequisites
+
+1. **pfSense** with [pfrest](https://github.com/pfrest/pfSense-pkg-RESTAPI) package installed
+2. A user account with API access (typically `admin`)
+
+## Configuration
+
+Set environment variables:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PFSENSE_HOST` | Yes | — | pfSense hostname or IP |
+| `PFSENSE_PASSWORD` | Yes | — | API user password |
+| `PFSENSE_USERNAME` | No | `admin` | API username |
+| `PFSENSE_PORT` | No | `443` | API port |
+| `PFSENSE_SCHEME` | No | `https` | `http` or `https` |
+| `PFSENSE_VERIFY_SSL` | No | `false` | Verify SSL certificate |
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pfsense": {
+      "command": "uvx",
+      "args": ["mcp-pfsense"],
+      "env": {
+        "PFSENSE_HOST": "10.10.10.1",
+        "PFSENSE_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add pfsense -- uvx mcp-pfsense
+```
+
+Then set environment variables in your shell or `.env` file.
+
+## Usage Examples
+
+Once connected, ask your AI assistant:
+
+- *"What's the pfSense system status?"*
+- *"Show me all firewall rules on the LAN interface"*
+- *"List active DHCP leases"*
+- *"Add a DNS entry for nas.home.lan pointing to 10.10.10.50"*
+- *"What devices are connected to the network?"* (ARP table)
+- *"Show gateway health and latency"*
+- *"Create a firewall rule to allow TCP port 8080 on LAN"*
+- *"Reserve IP 10.10.10.60 for MAC aa:bb:cc:dd:ee:20"*
+
+## API Compatibility
+
+- **pfSense**: 2.7.x (tested on 2.7.2)
+- **pfrest**: v2.x (REST API v2)
+- **Python**: 3.11+
+
+> **Note**: pfrest runs on nginx (port 80 by default), separate from the pfSense WebGUI (lighttpd on port 443). If your pfrest is configured on a non-standard port, set `PFSENSE_PORT` and `PFSENSE_SCHEME` accordingly.
+
+## Development
+
+```bash
+git clone https://github.com/antonio-mello-ai/mcp-pfsense.git
+cd mcp-pfsense
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint and type check
+ruff check .
+mypy src/
+```
+
+## License
+
+MIT

mcp_pfsense-0.1.0/README.md

@@ -0,0 +1,123 @@
+# mcp-pfsense
+
+[![PyPI](https://img.shields.io/pypi/v/mcp-pfsense)](https://pypi.org/project/mcp-pfsense/)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-pfsense)](https://pypi.org/project/mcp-pfsense/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for managing **pfSense firewalls** through AI assistants like Claude, ChatGPT, and Copilot.
+
+> **Requires**: [pfrest](https://github.com/pfrest/pfSense-pkg-RESTAPI) package installed on your pfSense instance (provides the REST API).
+
+## Features
+
+**17 tools** across 6 categories:
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **System** | `get_system_status`, `get_interfaces` | Version, CPU, memory, uptime, temperature, network interfaces |
+| **Firewall** | `list_firewall_rules`, `add_firewall_rule`, `delete_firewall_rule`, `list_firewall_aliases` | Rule management with interface filtering, alias listing |
+| **DHCP** | `list_dhcp_leases`, `list_dhcp_static_mappings`, `add_dhcp_static_mapping`, `delete_dhcp_static_mapping` | Active leases, IP reservations |
+| **DNS** | `list_dns_host_overrides`, `add_dns_host_override`, `delete_dns_host_override` | Unbound DNS Resolver host overrides |
+| **Monitoring** | `get_gateway_status`, `get_arp_table`, `list_services` | Gateway health, connected devices, service status |
+| **Services** | `restart_service` | Restart any pfSense service |
+
+### Safety
+
+All destructive operations (delete rules, delete mappings, restart services) require **two-step confirmation** — the tool returns a warning on first call and only executes when called again with `confirm=true`.
+
+## Installation
+
+```bash
+# Using uvx (recommended)
+uvx mcp-pfsense
+
+# Using pip
+pip install mcp-pfsense
+```
+
+### Prerequisites
+
+1. **pfSense** with [pfrest](https://github.com/pfrest/pfSense-pkg-RESTAPI) package installed
+2. A user account with API access (typically `admin`)
+
+## Configuration
+
+Set environment variables:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PFSENSE_HOST` | Yes | — | pfSense hostname or IP |
+| `PFSENSE_PASSWORD` | Yes | — | API user password |
+| `PFSENSE_USERNAME` | No | `admin` | API username |
+| `PFSENSE_PORT` | No | `443` | API port |
+| `PFSENSE_SCHEME` | No | `https` | `http` or `https` |
+| `PFSENSE_VERIFY_SSL` | No | `false` | Verify SSL certificate |
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pfsense": {
+      "command": "uvx",
+      "args": ["mcp-pfsense"],
+      "env": {
+        "PFSENSE_HOST": "10.10.10.1",
+        "PFSENSE_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add pfsense -- uvx mcp-pfsense
+```
+
+Then set environment variables in your shell or `.env` file.
+
+## Usage Examples
+
+Once connected, ask your AI assistant:
+
+- *"What's the pfSense system status?"*
+- *"Show me all firewall rules on the LAN interface"*
+- *"List active DHCP leases"*
+- *"Add a DNS entry for nas.home.lan pointing to 10.10.10.50"*
+- *"What devices are connected to the network?"* (ARP table)
+- *"Show gateway health and latency"*
+- *"Create a firewall rule to allow TCP port 8080 on LAN"*
+- *"Reserve IP 10.10.10.60 for MAC aa:bb:cc:dd:ee:20"*
+
+## API Compatibility
+
+- **pfSense**: 2.7.x (tested on 2.7.2)
+- **pfrest**: v2.x (REST API v2)
+- **Python**: 3.11+
+
+> **Note**: pfrest runs on nginx (port 80 by default), separate from the pfSense WebGUI (lighttpd on port 443). If your pfrest is configured on a non-standard port, set `PFSENSE_PORT` and `PFSENSE_SCHEME` accordingly.
+
+## Development
+
+```bash
+git clone https://github.com/antonio-mello-ai/mcp-pfsense.git
+cd mcp-pfsense
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint and type check
+ruff check .
+mypy src/
+```
+
+## License
+
+MIT

mcp_pfsense-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-pfsense"
+version = "0.1.0"
+description = "MCP server for managing pfSense firewalls through AI assistants"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Antonio Mello", email = "antonio.mello@felhen.com.br" },
+]
+keywords = ["mcp", "pfsense", "firewall", "ai", "llm", "server", "infrastructure"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking :: Firewalls",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic-settings>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+    "mypy>=1.13",
+    "build",
+    "twine",
+]
+
+[project.scripts]
+mcp-pfsense = "mcp_pfsense.server:main"
+
+[project.urls]
+Homepage = "https://github.com/antonio-mello-ai/mcp-pfsense"
+Repository = "https://github.com/antonio-mello-ai/mcp-pfsense"
+Issues = "https://github.com/antonio-mello-ai/mcp-pfsense/issues"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mcp_pfsense-0.1.0/src/mcp_pfsense/__init__.py

@@ -0,0 +1 @@
+"""MCP server for pfSense firewall management."""

mcp_pfsense-0.1.0/src/mcp_pfsense/client.py

@@ -0,0 +1,152 @@
+"""pfSense REST API client wrapper."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from mcp_pfsense.config import PfSenseConfig
+
+
+class PfSenseClient:
+    """Thin wrapper around the pfSense REST API (pfrest package).
+
+    Uses Basic Auth and communicates via JSON with the /api/v2 endpoints.
+    """
+
+    def __init__(self, config: PfSenseConfig) -> None:
+        self._config = config
+        self._client: httpx.Client | None = None
+
+    @property
+    def client(self) -> httpx.Client:
+        """Lazy-initialize and return the HTTP client."""
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self._config.base_url,
+                auth=(self._config.username, self._config.password),
+                verify=self._config.verify_ssl,
+                timeout=30.0,
+            )
+        return self._client
+
+    def _get(self, path: str, **params: Any) -> dict[str, Any]:
+        """Make a GET request and return the response data."""
+        resp = self.client.get(path, params=params or None)
+        resp.raise_for_status()
+        body: dict[str, Any] = resp.json()
+        return body
+
+    def _post(self, path: str, **data: Any) -> dict[str, Any]:
+        """Make a POST request and return the response data."""
+        resp = self.client.post(path, json=data or None)
+        resp.raise_for_status()
+        body: dict[str, Any] = resp.json()
+        return body
+
+    def _patch(self, path: str, **data: Any) -> dict[str, Any]:
+        """Make a PATCH request and return the response data."""
+        resp = self.client.patch(path, json=data or None)
+        resp.raise_for_status()
+        body: dict[str, Any] = resp.json()
+        return body
+
+    def _delete(self, path: str, **params: Any) -> dict[str, Any]:
+        """Make a DELETE request and return the response data."""
+        resp = self.client.delete(path, params=params or None)
+        resp.raise_for_status()
+        body: dict[str, Any] = resp.json()
+        return body
+
+    # --- System ---
+
+    def get_system_version(self) -> dict[str, Any]:
+        """Get pfSense version info."""
+        return self._get("/system/version")
+
+    def get_system_status(self) -> dict[str, Any]:
+        """Get system status (CPU, memory, uptime, temperature)."""
+        return self._get("/status/system")
+
+    # --- Interfaces ---
+
+    def get_interfaces(self) -> dict[str, Any]:
+        """List all network interfaces."""
+        return self._get("/interface")
+
+    # --- Firewall ---
+
+    def get_firewall_rules(self) -> dict[str, Any]:
+        """List all firewall rules."""
+        return self._get("/firewall/rule")
+
+    def create_firewall_rule(self, **params: Any) -> dict[str, Any]:
+        """Create a firewall rule."""
+        return self._post("/firewall/rule", **params)
+
+    def delete_firewall_rule(self, rule_id: int) -> dict[str, Any]:
+        """Delete a firewall rule by tracker ID."""
+        return self._delete("/firewall/rule", id=rule_id)
+
+    # --- DHCP ---
+
+    def get_dhcp_leases(self) -> dict[str, Any]:
+        """List active DHCP leases."""
+        return self._get("/status/dhcp_leases")
+
+    def get_dhcp_static_mappings(self, interface: str | None = None) -> dict[str, Any]:
+        """List DHCP static mappings."""
+        if interface:
+            return self._get("/services/dhcpd/static_mapping", interface=interface)
+        return self._get("/services/dhcpd/static_mapping")
+
+    def create_dhcp_static_mapping(self, **params: Any) -> dict[str, Any]:
+        """Create a DHCP static mapping."""
+        return self._post("/services/dhcpd/static_mapping", **params)
+
+    def delete_dhcp_static_mapping(self, mapping_id: int) -> dict[str, Any]:
+        """Delete a DHCP static mapping."""
+        return self._delete("/services/dhcpd/static_mapping", id=mapping_id)
+
+    # --- DNS ---
+
+    def get_dns_host_overrides(self) -> dict[str, Any]:
+        """List DNS Resolver host overrides."""
+        return self._get("/services/unbound/host_override")
+
+    def create_dns_host_override(self, **params: Any) -> dict[str, Any]:
+        """Create a DNS host override."""
+        return self._post("/services/unbound/host_override", **params)
+
+    def delete_dns_host_override(self, override_id: int) -> dict[str, Any]:
+        """Delete a DNS host override."""
+        return self._delete("/services/unbound/host_override", id=override_id)
+
+    # --- Gateways ---
+
+    def get_gateway_status(self) -> dict[str, Any]:
+        """Get gateway status (dual-WAN health)."""
+        return self._get("/status/gateway")
+
+    # --- ARP ---
+
+    def get_arp_table(self) -> dict[str, Any]:
+        """Get ARP table (connected devices)."""
+        return self._get("/diagnostics/arp_table")
+
+    # --- Services ---
+
+    def get_services_status(self) -> dict[str, Any]:
+        """List all services and their status."""
+        return self._get("/status/service")
+
+    def restart_service(self, name: str) -> dict[str, Any]:
+        """Restart a service by name."""
+        return self._post("/status/service", name=name, action="restart")
+
+    # --- Firewall Aliases ---
+
+    def get_firewall_aliases(self) -> dict[str, Any]:
+        """List firewall aliases."""
+        return self._get("/firewall/alias")

mcp_pfsense-0.1.0/src/mcp_pfsense/config.py

@@ -0,0 +1,28 @@
+"""Configuration for pfSense MCP server."""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings
+
+
+class PfSenseConfig(BaseSettings):
+    """pfSense connection settings loaded from environment variables."""
+
+    host: str
+    username: str = "admin"
+    password: str = ""
+    port: int = 443
+    verify_ssl: bool = False
+    scheme: str = "https"
+
+    model_config = {"env_prefix": "PFSENSE_"}
+
+    @classmethod
+    def from_env(cls) -> PfSenseConfig:
+        """Create config from environment variables."""
+        return cls()  # type: ignore[call-arg]
+
+    @property
+    def base_url(self) -> str:
+        """Build the base URL for the pfSense REST API."""
+        return f"{self.scheme}://{self.host}:{self.port}/api/v2"