NetWarden: Multi-Brand Home Network MCP Agent & Terraform Orchestrator

NetWarden is an intelligent Model Context Protocol (MCP) server and AI agent that seamlessly integrates into heterogeneous home and homelab networks. It allows AI models (such as Claude Desktop, Cursor, Antigravity, and Open-WebUI) to discover, configure, harden, and troubleshoot routers, managed switches, access points, and client devices across multiple brands—all backed by declarative Terraform / OpenTofu Infrastructure-as-Code.

🌟 Key Capabilities

• Multi-Brand Hardware Support: Uniform driver abstraction across Ubiquiti UniFi, MikroTik RouterOS, OPNsense / pfSense, OpenWrt, Cisco Catalyst / CBS, and Pi-hole.

• Zero-Hardware Simulation Mode: Built-in mock driver for immediate sandbox testing, CI/CD verification, and offline development without needing physical hardware attached.

• Declarative Infrastructure as Code (Terraform):

  • Generates structured HCL and network.tfvars.json from high-level network topology.

  • Native execution via terraform or tofu CLI, with built-in high-fidelity fallback simulation.

  • Real-time Drift Detection between live hardware state and declarative code.

• Safety Guardrails & Lockout Prevention:

  • Prevents accidental disconnection by safeguarding administrative MACs, gateway IPs, and the primary management plane.

  • Pre-execution risk assessment scoring (LOW, MEDIUM, HIGH, CRITICAL).

  • Automatic versioned state snapshots before applies with instant One-Click Rollback.

• Dedicated Scenario Engines:

  • Setup & Segmentation: Automated subnet allocation and zero-trust VLAN boundary rules (Management, Trusted LAN, IoT, Guest, Quarantine).

  • Zero-Trust Device Allowlisting: MAC-based admission control, static DHCP reservations, and automated containment for rogue devices.

  • Security Hardening: CIS and Homelab security audit engine with automated one-click remediation.

  • Diagnostics & Troubleshooting: Automated Layer 1 through Layer 7 triage (physical cable CRC error detection, link speed bottleneck diagnosis, latency, and firewall path evaluations).

Related MCP server: Network Sketcher

🏗️ Architecture Overview

graph TD
    User([User / AI Assistant]) -->|MCP Protocol / stdio / SSE| Server[NetWarden MCP Server]
    Server --> Safety[Safety Guardrails & Lockout Prevention]
    Safety --> Scenarios[Scenario Engines: Setup | Hardening | Allowlist | Diagnostics]
    Scenarios --> IaC[Terraform / OpenTofu Orchestrator]
    Scenarios --> Drivers[Multi-Brand Drivers Engine]
    
    Drivers --> UniFi[Ubiquiti UniFi Controller]
    Drivers --> MikroTik[MikroTik RouterOS v7]
    Drivers --> OPNsense[OPNsense / pfSense]
    Drivers --> OpenWrt[OpenWrt ubus / LuCI]
    Drivers --> Cisco[Cisco Managed Switches]
    Drivers --> Pihole[Pi-hole DNS Sinkhole]
    Drivers --> Mock[Simulated Network Lab]

    IaC --> StateManager[State Snapshots & Instant Rollback]

🚀 Quickstart & Installation

Prerequisites

• Python 3.10+

• Git

• (Optional) Terraform or OpenTofu CLI installed (brew install opentofu or brew install hashicorp/tap/terraform). If neither is installed, NetWarden operates in high-fidelity declarative simulation mode automatically.

1. Clone & Set Up Virtual Environment

git clone https://github.com/danielshaji1/home-network-mcp.git
cd home-network-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies and netwarden package
pip install -e ".[dev]"

2. Verify with the Test Suite

pytest -v tests

All 28 unit and integration tests will run and pass in under a second.

🔌 Connecting to MCP Clients

1. Claude Desktop

Add the following to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "netwarden": {
      "command": "/Users/danielshaji/home-network-mcp/.venv/bin/python",
      "args": ["/Users/danielshaji/home-network-mcp/mcp_server.py"]
    }
  }
}

2. Cursor IDE

In Cursor Settings > Features > MCP, click Add New MCP Server:

• Name: netwarden

• Type: command

• Command: /Users/danielshaji/home-network-mcp/.venv/bin/python /Users/danielshaji/home-network-mcp/mcp_server.py

3. Remote / Web Agents (SSE Transport)

To run NetWarden as a network service over Server-Sent Events (SSE):

python mcp_server.py --transport sse --host 0.0.0.0 --port 8000

🛠️ MCP Tools Reference

NetWarden registers 16 specialized tools with full Pydantic type inference and docstrings:

💻 Terminal CLI Utility

NetWarden includes a rich terminal CLI for direct command-line operations:

# View network topology and VLAN segments
netwarden topology

# List connected clients
netwarden clients

# Authorize a new device on IoT VLAN 30 with static DHCP IP
netwarden allow aa:bb:cc:dd:ee:ff 30 --name "Smart-Sensor" --ip 10.0.30.70 --category IoT

# Quarantine a rogue device into Quarantine Sandbox VLAN 99
netwarden quarantine aa:bb:cc:dd:ee:ff

# Run security hardening audit
netwarden audit

# Troubleshoot a degraded camera or host
netwarden diagnose Hikvision-Camera

# Preview declarative Terraform plan
netwarden plan

# Apply Terraform configuration with safety snapshot
netwarden apply

🔒 Safety Guardrails & Lockout Protection

Configuring routers and switches via AI automation requires fail-safe guardrails. NetWarden protects you by:

1. Never blocking admin devices: MAC addresses and IPs specified in protected_macs or protected_ips can never be dropped or quarantined.

2. Management Plane Invariant: Rules that would sever connectivity to the management interface are rejected before execution.

3. Subnet Conflict Prevention: VLAN subnet allocations are mathematically verified against CIDR overlaps.

4. Pre-Apply Snapshots: Every apply creates a versioned snapshot in terraform/backups/, enabling instant rollback with rollback_network_configuration().

📄 License

Distributed under the MIT License. See LICENSE for details.