{
  "markdown": "# <img src=\"https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/unifi-dark.png\" alt=\"UniFi Dark Logo\" width=\"40\" /> UniFi MCP Server\n\n[![CI](https://github.com/enuno/unifi-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/enuno/unifi-mcp-server/actions/workflows/ci.yml)\n[![Security](https://github.com/enuno/unifi-mcp-server/actions/workflows/security.yml/badge.svg)](https://github.com/enuno/unifi-mcp-server/actions/workflows/security.yml)\n[![codecov](https://codecov.io/github/enuno/unifi-mcp-server/graph/badge.svg?token=ZD314B59CE)](https://codecov.io/github/enuno/unifi-mcp-server)\n[![PyPI](https://img.shields.io/pypi/v/unifi-mcp-server.svg)](https://pypi.org/project/unifi-mcp-server/)\n[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/enuno/unifi-mcp-server)\n\nA Model Context Protocol (MCP) server that exposes the UniFi Network Controller API today and is evolving into a production-grade multi-domain platform for Protect, Access, and enterprise-scale orchestration.\n\nSee `SPEC.md` for the architecture target and `DEVELOPMENT_PLAN.md` for the phase roadmap.\n\n## Operator quick start\n\n### Objective\n\nGive operators a fast, safe reading order for understanding what the server does today, what it is becoming, and which docs govern rollout decisions.\n\n### Prerequisites\n\n- You know which UniFi API mode the deployment uses: local, cloud-ea, or cloud-v1.\n- You know whether the runtime is stdio, HTTP, SSE, or streamable HTTP.\n- You have read the phase target in `SPEC.md` and the current work item in `DEVELOPMENT_PLAN.md`.\n\n### Procedure\n\n1. Confirm the current stable release and current phase focus.\n2. Read `SPEC.md` for architecture intent and `DEVELOPMENT_PLAN.md` for sequencing.\n3. Use `API.md` and `docs/UNIFI_API.md` for implementation surface details.\n4. Use the phase runbooks in `NETWORK_PLAYBOOK.md`, `HARBOR_SETUP.md`, `MULTI_CONTROLLER.md`, `METRICS.md`, `WEBHOOK_SETUP.md`, and `A2A.md` when operating or extending phase 5 systems.\n5. For release work, consult `RELEASE_CHECKLIST.md` and `docs/RELEASE_PROCESS.md` before tagging or publishing.\n\n### Verification\n\n- The chosen API mode matches the runtime configuration.\n- The current phase and the documented roadmap agree.\n- The operator can point to the correct runbook before making a change.\n\n### Rollback\n\n- If the selected runbook does not match the deployed capability, stop and reconcile docs before changing production state.\n\n### Common failure modes\n\n- README claims outrun the codebase.\n- Operators follow phase language without checking the specific runbook.\n- Release or rollout decisions are made from the README alone instead of the canonical docs.\n\n## 📋 Version Notice\n\n**Current Stable Release**: 0.2.5 (May 1, 2026) 🎉\n\n**Installation:**\n\n```bash\npip install unifi-mcp-server\n```\n\n**Roadmap focus:**\n\n- Phase 3: native Protect API integration (camera/NVR/device/view/event read tools and resources now wired; PTZ and media streams still in progress)\n- Phase 4: testing, polish, minor gaps, runbooks, skills, and developer workflow hardening\n- Phase 5: multi-controller orchestration, dry-run, RBAC, audit logging, metrics, A2A, webhooks, Access API work, and tool exposure profiles\n\n**See:** [RELEASE_NOTES_0.2.5.md](RELEASE_NOTES_0.2.5.md) for complete changelog.\n\n## Current Development Posture\n\n- Current repo codebase: ~220 async tool functions across 40+ modules\n- Phases 0–2 are complete\n- Phase 3 (Protect API integration) is the active implementation target\n- The architectural target is documented in `SPEC.md`\n- The canonical roadmap is `DEVELOPMENT_PLAN.md`\n\n**Previous Release - v0.2.4 (2026-02-19):**\n\n- 🚨 **Critical Startup Fix (issue #42)** - `ImportError: cannot import 'config' from 'agnost'` prevented startup. Fixed by moving agnost imports inside the conditional block.\n- 📌 **Dependency Pin** - Excluded broken `agnost==0.1.13` from version range (`>=0.1.12,!=0.1.13`)\n- 🧪 **1,325 Tests Passing** - 1219 unit + 106 integration tests, cloud-ea API compatibility fixes, Site Manager endpoint hardening\n\n**Previous Release - v0.2.3 (2026-02-18):**\n\n- ✅ P1 API bug fixes (QoS audit_action, Site Manager decorator, Topology warnings, Backup client methods)\n- ✅ P2 RADIUS & Guest Portal — Complete CRUD (get/update for RADIUS accounts and hotspot packages)\n\n**Previous Release - v0.2.2 (2026-02-16):**\n\n- 🔌 **Port Profile Management** - 8 new tools for switch port configuration (PoE, VLAN, 802.1X, LLDP-MED)\n- 🔒 **Security Updates** - Critical dependency updates (FastMCP 2.14.5, MCP 1.26.0, cryptography 46.0.5)\n- 🧪 **1,068 Tests Passing** - 75 new tests, all passing across Python 3.10, 3.11, 3.12\n\n**Major Release - v0.2.0 (2026-01-25):**\n\n- ✨ **74 MCP Tools** - All 7 feature phases complete\n- 📦 **Published on PyPI** - Easy installation with pip/uv\n- 📊 **QoS Management** - Traffic prioritization and bandwidth control (11 tools)\n- 💾 **Backup & Restore** - Automated scheduling and verification (8 tools)\n- 🌐 **Multi-Site Aggregation** - Cross-site analytics and management (4 tools)\n- 🔒 **ACL & Traffic Filtering** - Advanced traffic control (7 tools)\n- 🏢 **Site Management** - Multi-site provisioning and VPN (9 tools)\n- 🔐 **RADIUS & Guest Portal** - 802.1X authentication (6 tools)\n- 🗺️ **Network Topology** - Complete topology mapping and visualization (5 tools)\n\nSee [CHANGELOG.md](CHANGELOG.md) for complete release notes and [VERIFICATION_REPORT.md](docs/archive/VERIFICATION_REPORT.md) for detailed verification.\n\n## 🌐 API Mode Support\n\nThe UniFi MCP Server supports **three distinct API modes** with different capabilities:\n\n### Local Gateway API (Recommended) ✅\n\n**Full feature support** - Direct access to your UniFi gateway.\n\n- ✅ **All Features Available**: Device management, client control, network configuration, firewall rules, WiFi management\n- ✅ **Real-time Data**: Access to live device/client statistics and detailed information\n- ✅ **Configuration Changes**: Create, update, delete networks, VLANs, firewall rules, SSIDs\n- 📍 **Requirement**: Local network access to your UniFi gateway (e.g., 192.168.2.1)\n- ⚙️ **Configuration**: `UNIFI_API_TYPE=local` + `UNIFI_LOCAL_HOST=<gateway-ip>`\n\n### Cloud Early Access API ⚠️\n\n**Site-centric access** - UniFi cloud API with limited but functional read-only capabilities.\n\n- ✅ **Site Management**: List sites, get site details (matches by `siteId`, `_id`, `name`, or `meta.name`)\n- ✅ **Site Manager API** (optional): Multi-site aggregation, host inventory, cross-site statistics\n  - Enable with `UNIFI_SITE_MANAGER_ENABLED=true`\n  - Gracefully degrades when endpoints are unavailable\n- ⚠️ **No Individual Device/Client Access**: Cannot query specific devices or clients\n- ⚠️ **No Configuration Changes**: Cannot modify networks, firewall rules, or settings\n- ⚙️ **Configuration**: `UNIFI_API_TYPE=cloud-ea` + optional `UNIFI_SITE_MANAGER_ENABLED=true`\n- 📊 **Rate Limit**: 100 requests/minute\n\n### Cloud V1 API ⚠️\n\n**Limited to aggregate statistics** - UniFi stable v1 cloud API.\n\n- ✅ **Site Information**: List sites with aggregate statistics (device counts, client counts, bandwidth)\n- ⚠️ **No Individual Device/Client Access**: Cannot query specific devices or clients\n- ⚠️ **No Configuration Changes**: Cannot modify networks, firewall rules, or settings\n- ⚙️ **Configuration**: `UNIFI_API_TYPE=cloud-v1`\n- 📊 **Rate Limit**: 10,000 requests/minute\n\n**💡 Recommendation**: Use **Local Gateway API** (`UNIFI_API_TYPE=local`) for full functionality. Cloud APIs are suitable only for high-level monitoring dashboards.\n\n## 🔌 Transport Modes\n\nThe UniFi MCP Server supports **multiple transport modes** for different deployment scenarios:\n\n### STDIO (Default) ✅\n\n**Local subprocess communication** — Best for Claude Desktop, Cursor, and local AI clients.\n\n- ✅ **Default mode**: No configuration needed\n- ✅ **Zero network overhead**: Direct stdin/stdout communication\n- ✅ **No port required**: Runs as a subprocess of the MCP client\n- ⚙️ **Configuration**: `MCP_SERVER_TRANSPORT=stdio` (default)\n\n### SSE (Server-Sent Events) 🌐 ⚠️ Deprecated\n\n**Network-accessible HTTP server** — legacy transport, kept for backward compatibility.\n\n- ⚠️ **Known issue**: client proxies such as `mcp-remote` can send the first tool call before the SSE `initialize` handshake finishes, which the MCP SDK rejects with `Received request before initialization was complete` (see [#96](https://github.com/enuno/unifi-mcp-server/issues/96)). This is a timing issue in the SSE transport itself (upstream in the `mcp` SDK / client proxy, not this server's tool logic), so it cannot be fixed from this codebase.\n- ✅ **Network access**: Connect from any MCP client over HTTP\n- ✅ **MCP gateway compatible**: Works with MCP gateways that consolidate servers\n- ⚙️ **Configuration**: `MCP_SERVER_TRANSPORT=sse` + `MCP_SERVER_PORT=3000`\n- 👉 **Prefer Streamable HTTP below** for any new network-accessible deployment.\n\n### HTTP 🌐\n\n**Standard HTTP transport** — Alternative network mode.\n\n- ⚙️ **Configuration**: `MCP_SERVER_TRANSPORT=http` + `MCP_SERVER_PORT=3000`\n\n### Streamable HTTP 🌐 ✅ Recommended for network access\n\n**Modern HTTP transport** — the current MCP transport standard, and the successor to SSE.\n\n- ✅ **Network access**: Connect from any MCP client over HTTP\n- ✅ **MCP gateway compatible**: Works with MCP gateways that consolidate servers\n- ✅ **No SSE handshake race**: session initialization is part of the same request/response cycle, avoiding the class of timing issue SSE has with proxies like `mcp-remote`\n- ⚙️ **Configuration**: `MCP_SERVER_TRANSPORT=streamable_http` + `MCP_SERVER_PORT=3000` + `MCP_AUTH_TOKEN=<token>`\n\n> ⚠️ **Authentication is required for network transports.** The MCP endpoint exposes every\n> registered tool, including destructive ones. `http`, `sse`, and `streamable_http` will refuse\n> to start unless `MCP_AUTH_TOKEN` is set; clients then send `Authorization: Bearer <token>`.\n> The server binds to `127.0.0.1` by default — terminate TLS and authenticate at a reverse proxy\n> before widening `MCP_SERVER_HOST` to `0.0.0.0`.\n\n**💡 Recommendation**: Use **STDIO** for local AI clients (Claude Desktop, Cursor). Use **Streamable HTTP** when running behind an authenticating MCP gateway or reverse proxy — prefer it over SSE, which is kept only for backward compatibility.\n\n## 🧭 Tool Exposure Profiles\n\nTo reduce context-window bloat, the server will support named exposure profiles that register only the tools relevant to a given UniFi application area.\n\n### Planned profiles\n\n- `network` — network, switching, WiFi, DHCP, DNS, traffic, and client tools\n- `protect` — cameras, NVRs, devices, views, events, talkback, and Protect workflows (read surfaces wired; PTZ/media streams still in progress)\n- `access` — doors, readers, credentials, visitors, and access-control workflows\n- `talk` — UniFi Talk devices, calls, lines, and telephony workflows\n- `drive` — UniFi Drive storage, files, sharing, and drive workflows\n- `read-only` — `get_*`, `list_*`, `stat_*`, and `search_*` tools only\n\n### Intended behavior\n\n- Keep the full tool surface available when no profile is selected\n- Expose fewer tools per session so agents do not carry unrelated UniFi modules in context\n- Make the server easier to use in application-specific deployments and focused agent workflows\n- Pair with `UNIFI_PROFILE` so profile selection is explicit and repeatable\n\n### Running in Streamable HTTP Mode (recommended for network access)\n\n```bash\n# Set transport to Streamable HTTP\nexport MCP_SERVER_TRANSPORT=streamable_http\nexport MCP_SERVER_PORT=3000\n# Required — the server refuses to start a network transport without it\nexport MCP_AUTH_TOKEN=$(openssl rand -hex 32)\n\n# Start the server (binds to 127.0.0.1 by default)\nunifi-mcp-server\n# Server listening on 127.0.0.1:3000 via streamable_http\n# Clients send: Authorization: Bearer $MCP_AUTH_TOKEN\n```\n\n### Docker Compose for Streamable HTTP Mode\n\n```yaml\nservices:\n  unifi-mcp:\n    image: ghcr.io/enuno/unifi-mcp-server:latest\n    environment:\n      UNIFI_API_KEY: your-api-key\n      UNIFI_API_TYPE: local\n      UNIFI_LOCAL_HOST: 192.168.2.1\n      MCP_SERVER_TRANSPORT: streamable_http\n      MCP_SERVER_PORT: 3000\n      MCP_SERVER_HOST: 0.0.0.0            # container-internal; keep the published port on loopback\n      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}   # required — clients send Authorization: Bearer <token>\n    ports:\n      # Published on loopback; put an authenticating TLS proxy in front to expose it further.\n      - \"127.0.0.1:3000:3000\"\n```\n\n### Connecting via MCP Gateway\n\nOnce running in Streamable HTTP mode, configure your MCP gateway to connect:\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"url\": \"http://your-server-ip:3000/mcp\"\n    }\n  }\n}\n```\n\n### Running in SSE Mode (deprecated)\n\nSSE is kept for backward compatibility only — see the [transport modes](#-transport-modes) section above for why Streamable HTTP is preferred. To run it anyway:\n\n```bash\nexport MCP_SERVER_TRANSPORT=sse\nexport MCP_SERVER_PORT=3000\nunifi-mcp-server\n# Server listening on 127.0.0.1:3000 via sse (MCP_AUTH_TOKEN required)\n```\n\n## Features\n\n### Core Network Management\n\n- **Device Management**: List, monitor, restart, locate, and upgrade UniFi devices (APs, switches, gateways)\n- **Network Configuration**: Create, update, and delete networks, VLANs, and subnets with DHCP configuration\n- **Client Management**: Query, block, unblock, and reconnect clients with detailed analytics\n- **WiFi/SSID Management**: Create and manage wireless networks with WPA2/WPA3, guest networks, and VLAN isolation\n- **Port Profile Management** (v0.2.2): Switch port configuration with PoE, VLAN trunking, 802.1X, LLDP-MED, speed/duplex\n- **Device Port Overrides** (v0.2.2): Per-port configuration on individual switches with smart merge capabilities\n- **Port Forwarding**: Configure port forwarding rules for external access\n- **DPI Statistics**: Deep Packet Inspection analytics for bandwidth usage by application and category\n- **Multi-Site Support**: Work with multiple UniFi sites seamlessly\n- **Real-time Monitoring**: Access device, network, client, and WiFi statistics\n\n### Security & Firewall (v0.2.0)\n\n- **Firewall Rules**: Create, update, and delete firewall rules with advanced traffic filtering\n- **ACL Management**: Layer 3/4 access control lists with rule ordering and priority\n- **Traffic Matching Lists**: IP, MAC, domain, and port-based traffic classification\n- **Zone-Based Firewall**: Modern zone-based security with zone management and zone-to-zone policies\n- **RADIUS Authentication**: 802.1X authentication with RADIUS server configuration\n- **Guest Portal**: Customizable captive portals with hotspot billing and voucher management\n\n### Quality of Service (v0.2.0)\n\n- **QoS Profiles**: Create and manage QoS profiles for traffic prioritization\n- **Traffic Routes**: Time-based routing with schedules and application awareness\n- **Bandwidth Management**: Upload/download limits with guaranteed minimums\n- **ProAV Mode**: Professional audio/video QoS templates\n- **Reference Profiles**: Built-in QoS templates for common applications\n\n### Backup & Operations (v0.2.0)\n\n- **Automated Backups**: Schedule backups with cron expressions\n- **Backup Management**: Create, download, restore, and delete backups\n- **Cloud Sync Tracking**: Monitor backup cloud synchronization status\n- **Checksum Verification**: Ensure backup integrity with SHA-256 checksums\n- **Multiple Backup Types**: Network configurations and full system backups\n\n### Multi-Site Management (v0.2.0)\n\n- **Site Provisioning**: Create, update, and delete UniFi sites\n- **Site-to-Site VPN**: Configure VPN tunnels between sites\n- **Device Migration**: Move devices between sites seamlessly\n- **Site Health Monitoring**: Track site health scores and metrics\n- **Cross-Site Analytics**: Aggregate device and client statistics across locations\n- **Configuration Export**: Export site configurations for backup/documentation\n\n### Network Topology (v0.2.0)\n\n- **Topology Discovery**: Complete network graph with devices and clients\n- **Connection Mapping**: Port-level device interconnections\n- **Multi-Format Export**: JSON, GraphML (Gephi), and DOT (Graphviz) formats\n- **Network Depth Analysis**: Identify network hierarchy and uplink relationships\n- **Visual Coordinates**: Optional device positioning for diagrams\n\n### Phase 5: Enterprise scale and operational excellence\n\n- **Redis Caching**: Optional Redis-based caching for improved performance (configurable TTL per resource type)\n- **Webhook Support**: Real-time event processing with HMAC signature verification\n- **Automatic Cache Invalidation**: Smart cache invalidation when configuration changes\n- **Event Handlers**: Built-in handlers for device, client, and alert events\n- **Performance Tracking**: Optional agnost.ai integration for monitoring MCP tool performance and usage analytics\n- **Operator Memory**: Optional Supermemory integration for persisting operator notes/context across tool calls, scoped per site\n- **Roadmap-aligned controls**: planned dry-run, RBAC, audit logging, metrics, and A2A discovery\n\n### Safety & Security\n\n- **Read-Only Mode**: Set `UNIFI_READ_ONLY=true` to register only non-mutating tools — state-changing tools are then absent from the MCP tool list entirely, rather than relying on a caller-supplied `confirm` flag\n- **Confirmation Required**: All mutating operations require explicit `confirm=True` flag\n- **Dry-Run Mode**: Planned change-safe preview path for all write and destructive operations\n- **Audit Logging**: Planned append-only audit trail for mutation paths\n- **Tool Scoping**: Planned API-key-based RBAC for least-privilege access\n- **Input Validation**: Comprehensive parameter validation with detailed error messages\n- **Password Masking**: Sensitive data automatically masked in logs\n- **Type-Safe**: Full type hints and Pydantic validation throughout\n- **Security Scanners**: CodeQL, Trivy, Bandit, Safety, and detect-secrets integration\n\n### Technical Excellence\n\n- **Async Support**: Built with async/await for high performance and concurrency\n- **MCP Protocol**: Standard Model Context Protocol for AI agent integration\n- **Comprehensive Testing**: 1,236 tests with high coverage, all passing across Python 3.10–3.13\n- **CI/CD Pipelines**: Automated testing, security scanning, and Docker builds (18 checks)\n- **Multi-Architecture**: Docker images for amd64, arm64, arm/v7 (32-bit ARM), and arm64/v8\n- **Security Hardened**: Updated critical dependencies (FastMCP, MCP SDK, cryptography)\n- **Quality Metrics**: Black formatting, Ruff linting, comprehensive type hints, Pydantic validation\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.10 or higher\n- A UniFi account at [unifi.ui.com](https://unifi.ui.com)\n- UniFi API key (obtain from Settings → Control Plane → Integrations)\n- Access to UniFi Cloud API or local gateway\n\n### Installation\n\n#### Using PyPI (Recommended)\n\nThe UniFi MCP Server is published on PyPI and can be installed with pip or uv:\n\n```bash\n# Install from PyPI\npip install unifi-mcp-server\n\n# Or using uv (faster)\nuv pip install unifi-mcp-server\n\n# Install specific version\npip install unifi-mcp-server==0.2.5\n```\n\nAfter installation, the `unifi-mcp-server` command will be available globally.\n\n**PyPI Package**: <https://pypi.org/project/unifi-mcp-server/>\n\n#### Using Docker (Alternative)\n\n```bash\n# Pull the latest release\ndocker pull ghcr.io/enuno/unifi-mcp-server:0.2.5\n\n# Multi-architecture support: amd64, arm64, arm/v7, arm64/v8\n```\n\n#### Build from Source (Development)\n\n##### Using uv (Recommended)\n\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone the repository\ngit clone https://github.com/enuno/unifi-mcp-server.git\ncd unifi-mcp-server\n\n# Create virtual environment and install dependencies\nuv venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\nuv pip install -e \".[dev]\"\n```\n\n#### Using pip\n\n```bash\n# Clone the repository\ngit clone https://github.com/enuno/unifi-mcp-server.git\ncd unifi-mcp-server\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install dependencies\npip install -e \".[dev]\"\n```\n\n#### Using Docker Compose (Recommended for Production)\n\nThe recommended way to run the UniFi MCP Server with full monitoring capabilities:\n\n```bash\n# 1. Copy and configure environment variables\ncp .env.docker.example .env\n# Edit .env with your UNIFI_API_KEY and AGNOST_ORG_ID\n\n# 2. Start all services (MCP Server + Redis + MCP Toolbox)\ndocker-compose up -d\n\n# 3. Check service status\ndocker-compose ps\n\n# 4. View logs\ndocker-compose logs -f unifi-mcp\n\n# 5. Access MCP Toolbox dashboard\nopen http://localhost:8080\n\n# 6. Stop all services\ndocker-compose down\n```\n\n**Included Services:**\n\n- **UniFi MCP Server**: Main MCP server with ~220 async tool functions\n- **MCP Toolbox**: Web-based analytics dashboard (port 8080)\n- **Redis**: High-performance caching layer\n\nSee [MCP_TOOLBOX.md](MCP_TOOLBOX.md) for detailed Toolbox documentation.\n\n#### Using Docker (Standalone)\n\nFor standalone Docker usage (not with MCP clients):\n\n```bash\n# Pull the image\ndocker pull ghcr.io/enuno/unifi-mcp-server:latest\n\n# Run the container in background (Cloud API)\n# Note: -i flag keeps stdin open for STDIO transport\ndocker run -i -d \\\n  --name unifi-mcp \\\n  -e UNIFI_API_KEY=your-api-key \\\n  -e UNIFI_API_TYPE=cloud \\\n  ghcr.io/enuno/unifi-mcp-server:latest\n\n# OR run with local gateway proxy\ndocker run -i -d \\\n  --name unifi-mcp \\\n  -e UNIFI_API_KEY=your-api-key \\\n  -e UNIFI_API_TYPE=local \\\n  -e UNIFI_HOST=192.168.2.1 \\\n  ghcr.io/enuno/unifi-mcp-server:latest\n\n# Check container status\ndocker ps --filter name=unifi-mcp\n\n# View logs\ndocker logs unifi-mcp\n\n# Stop and remove\ndocker rm -f unifi-mcp\n```\n\n**Note**: For MCP client integration (Claude Desktop, etc.), see the [Usage](#usage) section below for the correct configuration without `-d` flag.\n\n## Build from Source\n\n### Prerequisites\n\n- **Python 3.10+**: Required for running the server\n- **Git**: For cloning the repository\n- **uv** (recommended) or **pip**: For dependency management\n- **Docker** (optional): For containerized builds\n- **Node.js & npm** (optional): For npm package publishing\n\n### Development Build\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/enuno/unifi-mcp-server.git\ncd unifi-mcp-server\n```\n\n#### 2. Set Up Development Environment\n\n**Using uv (Recommended):**\n\n```bash\n# Install uv if not already installed\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Create virtual environment\nuv venv\n\n# Activate virtual environment\nsource .venv/bin/activate  # Linux/macOS\n# Or on Windows: .venv\\Scripts\\activate\n\n# Install development dependencies\nuv pip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\npre-commit install --hook-type commit-msg\n```\n\n**Using pip:**\n\n```bash\n# Create virtual environment\npython -m venv .venv\n\n# Activate virtual environment\nsource .venv/bin/activate  # Linux/macOS\n# Or on Windows: .venv\\Scripts\\activate\n\n# Upgrade pip\npip install --upgrade pip\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\npre-commit install --hook-type commit-msg\n```\n\n#### 3. Configure Environment\n\n```bash\n# Copy example configuration\ncp .env.example .env\n\n# Edit .env with your UniFi credentials\n# Required: UNIFI_API_KEY\n# Recommended: UNIFI_API_TYPE=local, UNIFI_LOCAL_HOST=<gateway-ip>\n```\n\n#### 4. Run Tests\n\n```bash\n# Run all unit tests\npytest tests/unit/ -v\n\n# Run with coverage report\npytest tests/unit/ --cov=src --cov-report=html --cov-report=term-missing\n\n# View coverage report\nopen htmlcov/index.html  # macOS\n# Or: xdg-open htmlcov/index.html  # Linux\n```\n\n#### 5. Run the Server\n\n```bash\n# Development mode with MCP Inspector\nuv run mcp dev src/main.py\n\n# Production mode\nuv run python -m src.main\n\n# The MCP Inspector will be available at http://localhost:5173\n```\n\n### Production Build\n\n#### Build Python Package\n\n```bash\n# Install build tools\nuv pip install build\n\n# Build wheel and source distribution\npython -m build\n\n# Output: dist/unifi_mcp_server-0.2.0-py3-none-any.whl\n#         dist/unifi_mcp_server-0.2.0.tar.gz\n```\n\n#### Build Docker Image\n\n```bash\n# Build for current architecture\ndocker build -t unifi-mcp-server:0.2.0 .\n\n# Build multi-architecture (requires buildx)\ndocker buildx create --use\ndocker buildx build \\\n  --platform linux/amd64,linux/arm64,linux/arm/v7 \\\n  -t ghcr.io/enuno/unifi-mcp-server:0.2.0 \\\n  --push .\n\n# Test the image\ndocker run -i --rm \\\n  -e UNIFI_API_KEY=your-key \\\n  -e UNIFI_API_TYPE=cloud \\\n  unifi-mcp-server:0.2.0\n```\n\n### Publishing\n\n#### Publish to PyPI\n\n```bash\n# Install twine\nuv pip install twine\n\n# Check distribution\ntwine check dist/*\n\n# Upload to PyPI (requires PyPI account and token)\ntwine upload dist/*\n\n# Or upload to Test PyPI first\ntwine upload --repository testpypi dist/*\n```\n\n#### Publish to npm (Metadata Wrapper)\n\n```bash\n# Ensure package.json is up to date\ncat package.json\n\n# Login to npm (if not already)\nnpm login\n\n# Publish package\nnpm publish --access public\n\n# Verify publication\nnpm view unifi-mcp-server\n```\n\n#### Publish to MCP Registry\n\n```bash\n# Install mcp-publisher\nbrew install mcp-publisher\n# Or: curl -L \"https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz\" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/\n\n# Authenticate with GitHub (for io.github.enuno namespace)\nmcp-publisher login github\n\n# Publish to registry (requires npm package published first)\nmcp-publisher publish\n\n# Verify\ncurl \"https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.enuno/unifi-mcp-server\"\n```\n\n### Release Process\n\nSee [docs/RELEASE_PROCESS.md](docs/RELEASE_PROCESS.md) for the complete release workflow, including automated GitHub Actions, manual PyPI/npm publishing, and MCP registry submission.\n\n### Configuration\n\n#### Obtaining Your API Key\n\n1. Log in to [UniFi Site Manager](https://unifi.ui.com)\n2. Navigate to **Settings → Control Plane → Integrations**\n3. Click **Create API Key**\n4. **Save the key immediately** - it's only shown once!\n5. Store it securely in your `.env` file\n\n#### Configuration File\n\nCreate a `.env` file in the project root:\n\n```env\n# Required: Your UniFi API Key\nUNIFI_API_KEY=your-api-key-here\n\n# API Mode Selection (choose one):\n# - 'local': Full access via local gateway (RECOMMENDED)\n# - 'cloud-ea': Early Access cloud API (limited to statistics)\n# - 'cloud-v1': Stable v1 cloud API (limited to statistics)\nUNIFI_API_TYPE=local\n\n# Local Gateway Configuration (for UNIFI_API_TYPE=local)\nUNIFI_LOCAL_HOST=192.168.2.1\nUNIFI_LOCAL_PORT=443\nUNIFI_LOCAL_VERIFY_SSL=false\n\n# Cloud API Configuration (for cloud-ea or cloud-v1)\n# UNIFI_CLOUD_API_URL=https://api.ui.com\n\n# Site Manager API (cloud-ea only, optional)\n# UNIFI_SITE_MANAGER_ENABLED=true\n\n# Optional settings\nUNIFI_DEFAULT_SITE=default\n\n# Redis caching (optional - improves performance)\nREDIS_HOST=localhost\nREDIS_PORT=6379\nREDIS_DB=0\n# REDIS_PASSWORD=your-password  # If Redis requires authentication\n\n# Webhook support (optional - for real-time events)\nWEBHOOK_SECRET=your-webhook-secret-here\n\n# Performance tracking with agnost.ai (optional - for analytics)\n# Get your Organization ID from https://app.agnost.ai\n# AGNOST_ENABLED=true\n# AGNOST_ORG_ID=your-organization-id-here\n# AGNOST_ENDPOINT=https://api.agnost.ai\n# AGNOST_DISABLE_INPUT=false  # Set to true to disable input tracking\n# AGNOST_DISABLE_OUTPUT=false # Set to true to disable output tracking\n\n# Supermemory (optional - operator notes/context storage, scoped per site)\n# Requires: pip install supermemory\n# Get your API key from https://console.supermemory.ai\n# SUPERMEMORY_ENABLED=true\n# SUPERMEMORY_API_KEY=your-supermemory-api-key-here\n```\n\nSee `.env.example` for all available options.\n\n### Running the Server\n\n```bash\n# Development mode with MCP Inspector\nuv run mcp dev src/main.py\n\n# Production mode\nuv run python src/main.py\n```\n\nThe MCP Inspector will be available at `http://localhost:5173` for interactive testing.\n\n## Usage\n\n### With Claude Desktop\n\nAdd to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n#### Option 1: Using PyPI Package (Recommended)\n\nAfter installing via `pip install unifi-mcp-server`:\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"command\": \"unifi-mcp-server\",\n      \"env\": {\n        \"UNIFI_API_KEY\": \"your-api-key-here\",\n        \"UNIFI_API_TYPE\": \"local\",\n        \"UNIFI_LOCAL_HOST\": \"192.168.2.1\"\n      }\n    }\n  }\n}\n```\n\nFor cloud API access, use:\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"command\": \"unifi-mcp-server\",\n      \"env\": {\n        \"UNIFI_API_KEY\": \"your-api-key-here\",\n        \"UNIFI_API_TYPE\": \"cloud-v1\"\n      }\n    }\n  }\n}\n```\n\n#### Option 2: Using uv with PyPI Package\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"command\": \"uvx\",\n      \"args\": [\"unifi-mcp-server\"],\n      \"env\": {\n        \"UNIFI_API_KEY\": \"your-api-key-here\",\n        \"UNIFI_API_TYPE\": \"local\",\n        \"UNIFI_LOCAL_HOST\": \"192.168.2.1\"\n      }\n    }\n  }\n}\n```\n\n#### Option 3: Using Docker\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-e\",\n        \"UNIFI_API_KEY=your-api-key-here\",\n        \"-e\",\n        \"UNIFI_API_TYPE=cloud\",\n        \"ghcr.io/enuno/unifi-mcp-server:latest\"\n      ]\n    }\n  }\n}\n```\n\n**Important**: Do NOT use `-d` (detached mode) in MCP client configurations. The MCP client needs to maintain a persistent stdin/stdout connection to the container.\n\n### With Cursor\n\nAdd to your Cursor MCP configuration (`mcp.json` via \"View: Open MCP Settings → New MCP Server\"):\n\n#### Option 1: Using PyPI Package (Recommended)\n\nAfter installing via `pip install unifi-mcp-server`:\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi-mcp\": {\n      \"command\": \"unifi-mcp-server\",\n      \"env\": {\n        \"UNIFI_API_KEY\": \"your-api-key-here\",\n        \"UNIFI_API_TYPE\": \"local\",\n        \"UNIFI_LOCAL_HOST\": \"192.168.2.1\",\n        \"UNIFI_LOCAL_VERIFY_SSL\": \"false\"\n      },\n      \"disabled\": false\n    }\n  }\n}\n```\n\n#### Option 2: Using uv with PyPI Package\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"unifi-mcp-server\"],\n      \"env\": {\n        \"UNIFI_API_KEY\": \"your-api-key-here\",\n        \"UNIFI_API_TYPE\": \"local\",\n        \"UNIFI_LOCAL_HOST\": \"192.168.2.1\"\n      },\n      \"disabled\": false\n    }\n  }\n}\n```\n\n#### Option 3: Using Docker\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"--name\", \"unifi-mcp-server\",\n        \"-e\", \"UNIFI_API_KEY=your_unifi_api_key_here\",\n        \"-e\", \"UNIFI_API_TYPE=local\",\n        \"-e\", \"UNIFI_LOCAL_HOST=192.168.2.1\",\n        \"-e\", \"UNIFI_LOCAL_VERIFY_SSL=false\",\n        \"ghcr.io/enuno/unifi-mcp-server:latest\"\n      ],\n      \"disabled\": false\n    }\n  }\n}\n```\n\n**Configuration Notes:**\n\n- Replace `UNIFI_API_KEY` with your actual UniFi API key\n- For local gateway access, set `UNIFI_API_TYPE=local` and provide `UNIFI_LOCAL_HOST`\n- For cloud API access, use `UNIFI_API_TYPE=cloud-v1` or `cloud-ea`\n- After saving, restart Cursor to activate the server\n- Invoke tools in the Chat sidebar (e.g., \"List my UniFi devices\")\n\n### With Other MCP Clients\n\nThe UniFi MCP Server works with any MCP-compatible client. Here are generic configuration patterns:\n\n#### Using the Installed Command\n\nAfter installing from PyPI (`pip install unifi-mcp-server`):\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"command\": \"unifi-mcp-server\",\n      \"env\": {\n        \"UNIFI_API_KEY\": \"your-api-key-here\",\n        \"UNIFI_API_TYPE\": \"local\",\n        \"UNIFI_LOCAL_HOST\": \"192.168.2.1\"\n      }\n    }\n  }\n}\n```\n\n#### Using uvx (Run from PyPI without installation)\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"command\": \"uvx\",\n      \"args\": [\"unifi-mcp-server\"],\n      \"env\": {\n        \"UNIFI_API_KEY\": \"your-api-key-here\",\n        \"UNIFI_API_TYPE\": \"local\",\n        \"UNIFI_LOCAL_HOST\": \"192.168.2.1\"\n      }\n    }\n  }\n}\n```\n\n#### Using Python Module Directly\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"src.main\"],\n      \"env\": {\n        \"UNIFI_API_KEY\": \"your-api-key-here\",\n        \"UNIFI_API_TYPE\": \"local\",\n        \"UNIFI_LOCAL_HOST\": \"192.168.2.1\"\n      }\n    }\n  }\n}\n```\n\n### Using as a Claude Code Skill\n\nThe repo ships a `SKILL.md` and four categorized skill files in `skills/` that let AI agents load UniFi context on-demand — without keeping all 215+ tool definitions in the LLM context for every conversation.\n\n#### Install the skill\n\n```bash\n# Personal skill (available in all Claude Code sessions)\ncp SKILL.md ~/.claude/skills/unifi.md\n\n# Or install all four domain skills individually\ncp skills/unifi-network.md   ~/.claude/skills/\ncp skills/unifi-devices.md   ~/.claude/skills/\ncp skills/unifi-security.md  ~/.claude/skills/\ncp skills/unifi-system.md    ~/.claude/skills/\n```\n\nOnce installed, Claude Code will automatically reference the skill when you ask about UniFi topics, without loading the full MCP server into every conversation.\n\n#### Scoped MCP profiles (reduce context footprint)\n\nYou can run the MCP server with only the tools you need by setting `UNIFI_PROFILE`:\n\n| Profile | Tools loaded | Best for |\n|---|---|---|\n| `network` | Clients, VLANs, WiFi, DHCP, DNS, vouchers | Day-to-day network ops |\n| `devices` | Inventory, control, ports, switching, topology | Hardware management |\n| `security` | Firewall, ZBF, ACLs, VPN, content filtering | Security audits |\n| `system` | Sites, backups, traffic flows, DPI, RADIUS | Monitoring & ops |\n| `minimal` | Sites + clients + devices only | Quick checks |\n\n```json\n{\n  \"mcpServers\": {\n    \"unifi-security\": {\n      \"command\": \"uvx\",\n      \"args\": [\"unifi-mcp-server\"],\n      \"env\": {\n        \"UNIFI_API_KEY\": \"your-api-key-here\",\n        \"UNIFI_API_TYPE\": \"local\",\n        \"UNIFI_LOCAL_HOST\": \"192.168.2.1\",\n        \"UNIFI_PROFILE\": \"security\"\n      }\n    }\n  }\n}\n```\n\nSee [docs/SKILLS.md](docs/SKILLS.md) for the full guide.\n\n**Environment Variables (All Clients):**\n\n- `UNIFI_API_KEY` (required): Your UniFi API key from unifi.ui.com\n- `UNIFI_API_TYPE` (required): `local`, `cloud-v1`, or `cloud-ea`\n- **For Local Gateway API**:\n  - `UNIFI_LOCAL_HOST`: Gateway IP (e.g., 192.168.2.1)\n  - `UNIFI_LOCAL_PORT`: Gateway port (default: 443)\n  - `UNIFI_LOCAL_VERIFY_SSL`: SSL verification (default: false)\n- **For Cloud APIs**:\n  - `UNIFI_CLOUD_API_URL`: Cloud API URL (default: <https://api.ui.com>)\n  - `UNIFI_DEFAULT_SITE`: Default site ID (default: default)\n  - `UNIFI_SITE_MANAGER_ENABLED`: Enable Site Manager multi-site tools for cloud-ea (default: false)\n- **Tool Scope (reduces LLM context size)**:\n  - `UNIFI_PROFILE`: Load only a subset of tools — `network`, `devices`, `security`, `system`, or `minimal` (default: all tools)\n- **MCP Server Transport**:\n  - `MCP_SERVER_TRANSPORT`: Transport mode (`stdio`, `sse`, `http`, `streamable_http`; default: `stdio`)\n  - `MCP_SERVER_HOST`: Bind address for network transports (default: `127.0.0.1`)\n  - `MCP_SERVER_PORT`: Server port (default: `3000`)\n  - `MCP_AUTH_TOKEN`: Bearer token required for network transports; comma-separate for several (default: unset — network transports refuse to start without it)\n\n### Programmatic Usage\n\n```python\nfrom mcp import MCP\nimport asyncio\n\nasync def main():\n    mcp = MCP(\"unifi-mcp-server\")\n\n    # List all devices\n    devices = await mcp.call_tool(\"list_devices\", {\n        \"site_id\": \"default\"\n    })\n\n    for device in devices:\n        print(f\"{device['name']}: {device['status']}\")\n\n    # Get network information via resource\n    networks = await mcp.read_resource(\"sites://default/networks\")\n    print(f\"Networks: {len(networks)}\")\n\n    # Create a guest WiFi network with VLAN isolation\n    wifi = await mcp.call_tool(\"create_wlan\", {\n        \"site_id\": \"default\",\n        \"name\": \"Guest WiFi\",\n        \"security\": \"wpapsk\",\n        \"password\": \"GuestPass123!\",\n        \"is_guest\": True,\n        \"vlan_id\": 100,\n        \"confirm\": True  # Required for safety\n    })\n    print(f\"Created WiFi: {wifi['name']}\")\n\n    # Get DPI statistics for top bandwidth users\n    top_apps = await mcp.call_tool(\"list_top_applications\", {\n        \"site_id\": \"default\",\n        \"limit\": 5,\n        \"time_range\": \"24h\"\n    })\n\n    for app in top_apps:\n        gb = app['total_bytes'] / 1024**3\n        print(f\"{app['application']}: {gb:.2f} GB\")\n\n    # Create Zone-Based Firewall zones (UniFi Network 9.0+)\n    lan_zone = await mcp.call_tool(\"create_firewall_zone\", {\n        \"site_id\": \"default\",\n        \"name\": \"LAN\",\n        \"description\": \"Trusted local network\",\n        \"confirm\": True\n    })\n\n    iot_zone = await mcp.call_tool(\"create_firewall_zone\", {\n        \"site_id\": \"default\",\n        \"name\": \"IoT\",\n        \"description\": \"Internet of Things devices\",\n        \"confirm\": True\n    })\n\n    # Set zone-to-zone policy (LAN can access IoT, but IoT cannot access LAN)\n    await mcp.call_tool(\"update_zbf_policy\", {\n        \"site_id\": \"default\",\n        \"source_zone_id\": lan_zone[\"_id\"],\n        \"destination_zone_id\": iot_zone[\"_id\"],\n        \"action\": \"accept\",\n        \"confirm\": True\n    })\n\nasyncio.run(main())\n```\n\n## API Documentation\n\nSee [API.md](API.md) for complete API documentation, including:\n\n- Available MCP tools\n- Resource URI schemes\n- Request/response formats\n- Error handling\n- Examples\n\n## Development\n\nCommand reference: [commands.md](commands.md)\n\n### Setup Development Environment\n\n```bash\n# Install development dependencies\nuv pip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\npre-commit install --hook-type commit-msg\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest tests/unit/\n\n# Run with coverage report\npytest tests/unit/ --cov=src --cov-report=html --cov-report=term-missing\n\n# Run specific test file\npytest tests/unit/test_zbf_tools.py -v\n\n# Run tests for the current feature set\npytest tests/unit/test_new_models.py tests/unit/test_zbf_tools.py tests/unit/test_traffic_flow_tools.py\n\n# Run only unit tests (fast)\npytest -m unit\n\n# Run only integration tests (requires UniFi controller)\npytest -m integration\n```\n\n**Current Test Coverage**:\n\n- 1,236 tests passing across Python 3.10-3.13\n- Coverage and module-level reporting are tracked in Codecov and CI\n- Module-specific targets are maintained in `DEVELOPMENT_PLAN.md` and the test suite\n\n[![Coverage Sunburst](https://codecov.io/github/enuno/unifi-mcp-server/graphs/sunburst.svg?token=ZD314B59CE)](https://codecov.io/github/enuno/unifi-mcp-server)\n\n**Coverage focus areas:**\n\n- Models and validation layers\n- Core tool paths and safety controls\n- Network, security, and operations surfaces\n- Utilities and helpers\n\n**Top Coverage Performers** (>95%):\n\n- clients.py: 98.72%\n- devices.py: 98.44%\n- device_control.py: 99.10%\n- topology.py: 95.83% ⭐ (v0.2.0)\n- vouchers.py: 96.36%\n- firewall.py: 96.11%\n\nSee [VERIFICATION_REPORT.md](docs/archive/VERIFICATION_REPORT.md) for complete coverage details and [TESTING_PLAN.md](docs/archive/TESTING_PLAN.md) for testing strategy.\n\n### Code Quality\n\n```bash\n# Format code\nblack src/ tests/\nisort src/ tests/\n\n# Lint code\nruff check src/ tests/ --fix\n\n# Type check\nmypy src/\n\n# Run all pre-commit checks\npre-commit run --all-files\n```\n\n### Testing with MCP Inspector\n\n```bash\n# Start development server with inspector\nuv run mcp dev src/main.py\n\n# Open http://localhost:5173 in your browser\n```\n\n## Project Structure\n\n```\nunifi-mcp-server/\n├── .github/\n│   └── workflows/          # CI/CD pipelines (CI, security, release)\n├── .claude/\n│   └── commands/          # Custom slash commands for development\n├── bin/\n│   └── unifi-cli          # Shell wrapper for CLI invocation\n├── skills/                # Categorized skill files for AI agents\n│   ├── unifi-network.md   # Clients, VLANs, WiFi, DHCP, DNS, vouchers\n│   ├── unifi-devices.md   # Device management, ports, switching, topology\n│   ├── unifi-security.md  # Firewall, ZBF, ACLs, VPN, content filtering\n│   └── unifi-system.md    # Sites, backups, traffic flows, DPI, RADIUS\n├── src/\n│   ├── main.py            # MCP server entry point (215+ tools registered)\n│   ├── cache.py           # Redis caching implementation\n│   ├── memory.py          # Supermemory operator notes/context storage\n│   ├── config/            # Configuration management\n│   ├── api/               # UniFi API client with rate limiting\n│   ├── models/            # Pydantic data models\n│   │   └── zbf.py         # Zone-Based Firewall models\n│   ├── tools/             # MCP tool definitions\n│   │   ├── clients.py     # Client query tools\n│   │   ├── devices.py     # Device query tools\n│   │   ├── networks.py    # Network query tools\n│   │   ├── sites.py       # Site query tools\n│   │   ├── firewall.py    # Firewall management (Phase 4)\n│   │   ├── firewall_zones.py  # Zone-Based Firewall zone management (v0.1.4)\n│   │   ├── zbf_matrix.py  # Zone-Based Firewall policy matrix (v0.1.4)\n│   │   ├── network_config.py  # Network configuration (Phase 4)\n│   │   ├── device_control.py  # Device control (Phase 4)\n│   │   ├── client_management.py  # Client management (Phase 4)\n│   │   ├── wifi.py        # WiFi/SSID management (Phase 5)\n│   │   ├── port_forwarding.py  # Port forwarding (Phase 5)\n│   │   └── dpi.py         # DPI statistics (Phase 5)\n│   ├── resources/         # MCP resource definitions\n│   ├── webhooks/          # Webhook receiver and handlers (Phase 5)\n│   └── utils/             # Utility functions and validators\n├── tests/\n│   ├── unit/              # Unit tests (213 tests, 37% coverage)\n│   ├── integration/       # Integration tests (planned)\n│   └── performance/       # Performance benchmarks (planned)\n├── docs/                  # Additional documentation\n│   └── AI-Coding/         # AI coding guidelines\n├── .env.example           # Environment variable template\n├── pyproject.toml         # Project configuration\n├── README.md              # This file\n├── SKILL.md               # Top-level AI agent skill manifest\n├── API.md                 # Complete API documentation\n├── DEVELOPMENT_PLAN.md    # Development roadmap\n├── docs/archive/          # Archived planning & session docs\n├── CONTRIBUTING.md        # Contribution guidelines\n├── SECURITY.md            # Security policy and best practices\n├── AGENTS.md              # AI agent guidelines\n└── LICENSE                # Apache 2.0 License\n```\n\n## Contributing\n\nWe welcome contributions from both human developers and AI coding assistants! Please see:\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines\n- [AGENTS.md](AGENTS.md) - AI agent-specific guidelines\n- [AI_CODING_ASSISTANT.md](AI_CODING_ASSISTANT.md) - AI coding standards\n- [AI_GIT_PRACTICES.md](AI_GIT_PRACTICES.md) - AI Git practices\n\n### Quick Contribution Guide\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/your-feature-name`\n3. Make your changes\n4. Run tests and linting: `pytest && pre-commit run --all-files`\n5. Commit with conventional commits: `feat: add new feature`\n6. Push and create a pull request\n\n### Automated Bug Reports\n\nFound a bug? Issues with `[Bug]` in the title are automatically analyzed by our AI bug handler:\n\n- **Instant Response**: Get immediate feedback on your bug report\n- **Smart Analysis**: AI determines if it's a real bug or usage issue\n- **Auto-Fix**: Simple bugs may be automatically fixed with a PR\n- **Helpful Guidance**: Usage issues receive documentation and examples\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md#automated-workflows) for more details.\n\n## Security\n\nSecurity is a top priority. Please see [SECURITY.md](SECURITY.md) for:\n\n- Reporting vulnerabilities\n- Security best practices\n- Supported versions\n\n**Never commit credentials or sensitive data!**\n\n## Roadmap\n\n### Version 0.2.0 (Current - Complete ✅ 2026-01-25)\n\n**All 7 Feature Phases Complete - 74 MCP Tools**\n\n**Phase 3: Read-Only Operations (16 tools)**\n\n- [x] Device management (list, details, statistics, search by type)\n- [x] Client management (list, details, statistics, search)\n- [x] Network information (details, VLANs, subnets, statistics)\n- [x] Site management (list, details, statistics)\n- [x] MCP resources (sites, devices, clients, networks)\n\n**Phase 4: Mutating Operations with Safety (13 tools)**\n\n- [x] Firewall rule management (create, update, delete)\n- [x] Network configuration (create, update, delete networks/VLANs)\n- [x] Device control (restart, locate, upgrade)\n- [x] Client management (block, unblock, reconnect)\n- [x] Safety mechanisms (confirmation, dry-run, audit logging)\n\n**Phase 5: Enterprise scale and operational excellence (11 tools)**\n\n- [x] WiFi/SSID management (create, update, delete, statistics)\n- [x] Port forwarding configuration (create, delete, list)\n- [x] DPI statistics (site-wide, top apps, per-client)\n- [x] Redis caching with automatic invalidation\n- [x] Webhook support for real-time events\n\n**Phase 6: Zone-Based Firewall (12 working tools)**\n\n- [x] Zone management (create, update, delete, list, assign networks) - 7 tools ✅ WORKING\n- [x] **Zone-to-zone policies via Firewall Policies v2 API** - 5 tools ✅ WORKING (PR #13)\n- [x] Legacy zone matrix endpoints - 5 tools ❌ ENDPOINTS DO NOT EXIST (use v2 API instead)\n- [x] Application blocking per zone (DPI-based blocking) - 2 tools ❌ ENDPOINTS DO NOT EXIST\n- [x] Zone statistics and monitoring - 1 tool ❌ ENDPOINT DOES NOT EXIST\n- [x] Type-safe Pydantic models for ZBF and Firewall Policies\n- [x] Comprehensive unit tests (84% coverage)\n- [x] Endpoint verification on U7 Express and UDM Pro (v10.0.156)\n\n**Phase 7: Traffic Flow Monitoring (15 tools) ✅ COMPLETE**\n\n- [x] Real-time traffic flow monitoring and analysis\n- [x] Flow filtering by IP, protocol, application, time range\n- [x] Connection state tracking (active, closed, timed-out)\n- [x] Client traffic aggregation with top applications/destinations\n- [x] Bandwidth rate calculations for streaming flows\n- [x] Security quick-response capabilities (block suspicious IPs)\n- [x] Type-safe Pydantic models for traffic flows\n- [x] Comprehensive unit tests (86.62% coverage)\n- [x] Advanced analytics and reporting capabilities\n\n**ZBF Implementation Notes (Verified 2025-11-18):**\n\n- ✅ Zone CRUD operations work (local gateway API only)\n- ✅ **Zone-to-zone policies work via Firewall Policies v2 API** (local gateway API only)\n- ❌ Legacy zone matrix endpoints NOT available via API (use v2 API instead)\n- ❌ Application blocking per zone NOT available via API\n- ❌ Zone statistics NOT available via API\n- See docs/archive/ZBF_STATUS.md for complete details and examples\n\n**Phase 1: QoS Enhancements (11 tools) ✅**\n\n- [x] QoS profile management (CRUD operations)\n- [x] Reference profiles and ProAV templates\n- [x] Traffic routing with time-based schedules\n- [x] Application-based QoS configuration\n- [x] Coverage: 82.43% (46 tests passing)\n\n**Phase 2: Backup & Restore (8 tools) ✅**\n\n- [x] Manual and automated backup creation\n- [x] Backup listing, download, and verification\n- [x] Backup restore functionality\n- [x] Automated scheduling with cron expressions\n- [x] Cloud synchronization tracking\n- [x] Coverage: 86.32% (10 tests passing)\n\n**Phase 3: Multi-Site Aggregation (4 tools) ✅**\n\n- [x] Cross-site device and client analytics\n- [x] Site health monitoring with scoring\n- [x] Side-by-side site comparison\n- [x] Consolidated reporting across locations\n- [x] Coverage: 92.95% (10 tests passing)\n\n**Phase 4: ACL & Traffic Filtering (7 tools) ✅**\n\n- [x] Layer 3/4 access control list management\n- [x] Traffic matching lists (IP, MAC, domain, port)\n- [x] Firewall policy automation\n- [x] Rule ordering and priority\n- [x] Coverage: 89.30-93.84%\n\n**Phase 5: Site Management Enhancements (9 tools) ✅**\n\n- [x] Multi-site provisioning and configuration\n- [x] Site-to-site VPN setup\n- [x] Device migration between sites\n- [x] Advanced site settings management\n- [x] Configuration export for backup\n- [x] Coverage: 92.95% (10 tests passing)\n\n**Phase 6: RADIUS & Guest Portal (6 tools) ✅**\n\n- [x] RADIUS profile configuration (802.1X)\n- [x] RADIUS accounting server support\n- [x] Guest portal customization\n- [x] Hotspot billing and voucher management\n- [x] Session timeout and redirect control\n- [x] Coverage: 69.77% (17 tests passing)\n\n**Phase 7: Network Topology (5 tools) ✅**\n\n- [x] Complete topology graph retrieval\n- [x] Multi-format export (JSON, GraphML, DOT)\n- [x] Device interconnection mapping\n- [x] Port-level connection tracking\n- [x] Network depth analysis\n- [x] Coverage tracked in Codecov and CI\n\n**Quality Achievements:**\n\n- [x] 1,236 tests passing\n- [x] 18/18 CI/CD checks passing\n- [x] Zero security vulnerabilities\n- [x] 30+ AI assistant example prompts\n- [x] Comprehensive documentation (docs/archive/VERIFICATION_REPORT.md, API.md)\n\n**Total: 74 MCP tools + Comprehensive documentation and verification**\n\n### Version 0.3.0 (Future - Planned)\n\n- [ ] VPN Management (site_vpn.py - 0% coverage currently)\n- [ ] WAN Management (wans.py - 0% coverage currently)\n- [ ] Enhanced ZBF Matrix (zbf_matrix.py - improve 65% coverage)\n- [ ] Integration tests for caching and webhooks\n- [ ] Performance benchmarks and optimization\n- [ ] Additional DPI analytics (historical trends)\n- [ ] Bulk device/client operations\n- [ ] Advanced traffic flow analytics\n\n### Version 1.0.0 (Future)\n\n- [ ] Complete UniFi API coverage (remaining endpoints)\n- [ ] Advanced analytics dashboard\n- [ ] VPN configuration management\n- [ ] Alert and notification management\n- [ ] Bulk operations for devices\n- [ ] Traffic shaping and QoS management\n\n## Acknowledgments\n\nThis project is inspired by and builds upon:\n\n- [sirkirby/unifi-network-mcp](https://github.com/sirkirby/unifi-network-mcp) - Reference implementation\n- [MakeWithData UniFi MCP Guide](https://www.makewithdata.tech/p/build-a-mcp-server-for-ai-access) - Tutorial and guide\n- [Anthropic MCP](https://github.com/anthropics/mcp) - Model Context Protocol specification\n- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/enuno/unifi-mcp-server/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/enuno/unifi-mcp-server/discussions)\n- **Documentation**: See [API.md](API.md) and other docs in this repository\n\n## Links\n\n- **Repository**: <https://github.com/enuno/unifi-mcp-server>\n- **Releases**: <https://github.com/enuno/unifi-mcp-server/releases>\n- **Docker Registry**: <https://ghcr.io/enuno/unifi-mcp-server>\n- **npm Package**: <https://www.npmjs.com/package/unifi-mcp-server>\n- **MCP Registry**: Search for `io.github.enuno/unifi-mcp-server` at <https://registry.modelcontextprotocol.io>\n- **Documentation**: [API.md](API.md) | [SKILLS.md](docs/SKILLS.md) | [VERIFICATION_REPORT.md](docs/archive/VERIFICATION_REPORT.md)\n- **UniFi Official**: <https://www.ui.com/>\n\n## 🌟 Star History\n\nIf you find this project useful, please consider starring it on GitHub to help others discover it!\n\n[![Star History Chart](https://api.star-history.com/svg?repos=enuno/unifi-mcp-server&type=date&legend=top-left)](https://www.star-history.com/#enuno/unifi-mcp-server&type=date&legend=top-left)\n\n---\n\nMade with ❤️ for the UniFi and AI communities\n",
  "bytes": 51745,
  "sha": "b070ce430a572e5a89612f1492dbdc396a02eefb9687299d3e6018a8131c01ec",
  "repo_slug": "enuno/unifi-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_enuno_unifi_mcp_server_3b68ce76/readme"
}