# Unifi Mcp Server

> An MCP server that leverages official UniFi API

- **Type:** MCP server
- **Install:** `agentstack add mcp-enuno-unifi-mcp-server`
- **Verified:** Pending review
- **Seller:** [enuno](https://agentstack.voostack.com/s/enuno)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [enuno](https://github.com/enuno)
- **Source:** https://github.com/enuno/unifi-mcp-server

## Install

```sh
agentstack add mcp-enuno-unifi-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

#  UniFi MCP Server

[](https://github.com/enuno/unifi-mcp-server/actions/workflows/ci.yml)
[](https://github.com/enuno/unifi-mcp-server/actions/workflows/security.yml)
[](https://codecov.io/github/enuno/unifi-mcp-server)
[](https://pypi.org/project/unifi-mcp-server/)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://deepwiki.com/enuno/unifi-mcp-server)

A Model Context Protocol (MCP) server that exposes the UniFi Network Controller API, enabling AI agents and applications to interact with UniFi network infrastructure in a standardized way.

## 📋 Version Notice

**Current Stable Release**: 0.2.5 (May 1, 2026) 🎉

**Installation:**

```bash
pip install unifi-mcp-server
```

**What's New in v0.2.5:**

- 🚀 **SSE/HTTP Transport Mode** - Direct HTTP connectivity for MCP gateway integration with long-lived persistent bidirectional communication channels. Enable with `UNIFI_TRANSPORT_MODE=sse` and `UNIFI_HTTP_PORT=8000`.
- 🔧 **API Compatibility Fixes** - 7 critical UniFi Network 9.x fixes including firewall policy zone resolution, WLAN band parameter handling, and response parsing
- ☁️ **Cloud EA API Hardening** - Enhanced Site Manager endpoint resilience with graceful fallbacks and improved error handling
- 🔐 **Security Updates** - Dependency bumps: fastmcp → latest, MCP framework → 1.26.0+, cryptography → 46.0.5+, httpx → 0.28.1+
- 🧪 **1,236 Tests Passing** - Maintained high coverage across Python 3.10–3.13

**See:** [RELEASE_NOTES_0.2.5.md](RELEASE_NOTES_0.2.5.md) for complete changelog.

## Current Development Posture

- Current repo codebase: ~215 async tool functions across 40+ modules
- Phases 0–2 are complete
- Phase 3 (Protect API integration) is the active implementation target
- Phase 4 adds testing, polish, minor gaps, runbooks, skills, and developer workflow hardening
- Phase 5 adds multi-controller orchestration, dry-run, RBAC, audit logging, metrics, A2A, webhooks, Access API work, and tool exposure modes for context reduction
- Canonical roadmap: `DEVELOPMENT_PLAN.md`

**Previous Release - v0.2.4 (2026-02-19):**

- 🚨 **Critical Startup Fix (issue #42)** - `ImportError: cannot import 'config' from 'agnost'` prevented startup. Fixed by moving agnost imports inside the conditional block.
- 📌 **Dependency Pin** - Excluded broken `agnost==0.1.13` from version range (`>=0.1.12,!=0.1.13`)
- 🧪 **1,325 Tests Passing** - 1219 unit + 106 integration tests, cloud-ea API compatibility fixes, Site Manager endpoint hardening

**Previous Release - v0.2.3 (2026-02-18):**

- ✅ P1 API bug fixes (QoS audit_action, Site Manager decorator, Topology warnings, Backup client methods)
- ✅ P2 RADIUS & Guest Portal — Complete CRUD (get/update for RADIUS accounts and hotspot packages)

**Previous Release - v0.2.2 (2026-02-16):**

- 🔌 **Port Profile Management** - 8 new tools for switch port configuration (PoE, VLAN, 802.1X, LLDP-MED)
- 🔒 **Security Updates** - Critical dependency updates (FastMCP 2.14.5, MCP 1.26.0, cryptography 46.0.5)
- 🧪 **1,068 Tests Passing** - 75 new tests, all passing across Python 3.10, 3.11, 3.12

**Major Release - v0.2.0 (2026-01-25):**

- ✨ **74 MCP Tools** - All 7 feature phases complete
- 📦 **Published on PyPI** - Easy installation with pip/uv
- 📊 **QoS Management** - Traffic prioritization and bandwidth control (11 tools)
- 💾 **Backup & Restore** - Automated scheduling and verification (8 tools)
- 🌐 **Multi-Site Aggregation** - Cross-site analytics and management (4 tools)
- 🔒 **ACL & Traffic Filtering** - Advanced traffic control (7 tools)
- 🏢 **Site Management** - Multi-site provisioning and VPN (9 tools)
- 🔐 **RADIUS & Guest Portal** - 802.1X authentication (6 tools)
- 🗺️ **Network Topology** - Complete topology mapping and visualization (5 tools)

See [CHANGELOG.md](CHANGELOG.md) for complete release notes and [VERIFICATION_REPORT.md](docs/archive/VERIFICATION_REPORT.md) for detailed verification.

## 🌐 API Mode Support

The UniFi MCP Server supports **three distinct API modes** with different capabilities:

### Local Gateway API (Recommended) ✅

**Full feature support** - Direct access to your UniFi gateway.

- ✅ **All Features Available**: Device management, client control, network configuration, firewall rules, WiFi management
- ✅ **Real-time Data**: Access to live device/client statistics and detailed information
- ✅ **Configuration Changes**: Create, update, delete networks, VLANs, firewall rules, SSIDs
- 📍 **Requirement**: Local network access to your UniFi gateway (e.g., 192.168.2.1)
- ⚙️ **Configuration**: `UNIFI_API_TYPE=local` + `UNIFI_LOCAL_HOST=`

### Cloud Early Access API ⚠️

**Site-centric access** - UniFi cloud API with limited but functional read-only capabilities.

- ✅ **Site Management**: List sites, get site details (matches by `siteId`, `_id`, `name`, or `meta.name`)
- ✅ **Site Manager API** (optional): Multi-site aggregation, host inventory, cross-site statistics
  - Enable with `UNIFI_SITE_MANAGER_ENABLED=true`
  - Gracefully degrades when endpoints are unavailable
- ⚠️ **No Individual Device/Client Access**: Cannot query specific devices or clients
- ⚠️ **No Configuration Changes**: Cannot modify networks, firewall rules, or settings
- ⚙️ **Configuration**: `UNIFI_API_TYPE=cloud-ea` + optional `UNIFI_SITE_MANAGER_ENABLED=true`
- 📊 **Rate Limit**: 100 requests/minute

### Cloud V1 API ⚠️

**Limited to aggregate statistics** - UniFi stable v1 cloud API.

- ✅ **Site Information**: List sites with aggregate statistics (device counts, client counts, bandwidth)
- ⚠️ **No Individual Device/Client Access**: Cannot query specific devices or clients
- ⚠️ **No Configuration Changes**: Cannot modify networks, firewall rules, or settings
- ⚙️ **Configuration**: `UNIFI_API_TYPE=cloud-v1`
- 📊 **Rate Limit**: 10,000 requests/minute

**💡 Recommendation**: Use **Local Gateway API** (`UNIFI_API_TYPE=local`) for full functionality. Cloud APIs are suitable only for high-level monitoring dashboards.

## 🔌 Transport Modes

The UniFi MCP Server supports **multiple transport modes** for different deployment scenarios:

### STDIO (Default) ✅

**Local subprocess communication** — Best for Claude Desktop, Cursor, and local AI clients.

- ✅ **Default mode**: No configuration needed
- ✅ **Zero network overhead**: Direct stdin/stdout communication
- ✅ **No port required**: Runs as a subprocess of the MCP client
- ⚙️ **Configuration**: `MCP_SERVER_TRANSPORT=stdio` (default)

### SSE (Server-Sent Events) 🌐

**Network-accessible HTTP server** — Best for MCP gateways and consolidating multiple MCPs.

- ✅ **Network access**: Connect from any MCP client over HTTP
- ✅ **MCP gateway compatible**: Works with MCP gateways that consolidate servers
- ✅ **Real-time streaming**: Long-lived connections for continuous communication
- ⚙️ **Configuration**: `MCP_SERVER_TRANSPORT=sse` + `MCP_SERVER_PORT=3000`

### HTTP 🌐

**Standard HTTP transport** — Alternative network mode.

- ⚙️ **Configuration**: `MCP_SERVER_TRANSPORT=http` + `MCP_SERVER_PORT=3000`

### Streamable HTTP 🌐

**Modern HTTP transport** — Latest MCP transport standard.

- ⚙️ **Configuration**: `MCP_SERVER_TRANSPORT=streamable_http` + `MCP_SERVER_PORT=3000`

**💡 Recommendation**: Use **STDIO** for local AI clients (Claude Desktop, Cursor). Use **SSE** when running behind an MCP gateway to consolidate multiple MCP servers into a single URL.

## 🧭 Tool Exposure Modes (Planned)

To reduce context-window bloat, the server will add named tool-exposure modes that only register the tools relevant to a given UniFi application area.

### Planned modes

- `network` — network, switching, WiFi, DHCP, DNS, traffic, and client tools
- `protect` — cameras, NVR, events, talkback, and Protect workflows
- `access` — doors, readers, credentials, visitors, and access-control workflows
- `talk` — UniFi Talk devices, calls, lines, and telephony workflows
- `drive` — UniFi Drive storage, files, sharing, and drive workflows
- `read-only` — `get_*`, `list_*`, `stat_*`, and `search_*` tools only

### Intended behavior

- Keep the full tool surface available when no mode is selected
- Expose fewer tools per session so agents do not carry unrelated UniFi modules in context
- Make the server easier to use in application-specific deployments and focused agent workflows
- Pair with `UNIFI_PROFILE` so mode selection is explicit and repeatable

### Running in SSE Mode

```bash
# Set transport to SSE
export MCP_SERVER_TRANSPORT=sse
export MCP_SERVER_PORT=3000

# Start the server
unifi-mcp-server
# Server listening on 0.0.0.0:3000 via sse
```

### Docker Compose for SSE Mode

```yaml
services:
  unifi-mcp:
    image: ghcr.io/enuno/unifi-mcp-server:latest
    environment:
      UNIFI_API_KEY: your-api-key
      UNIFI_API_TYPE: local
      UNIFI_LOCAL_HOST: 192.168.2.1
      MCP_SERVER_TRANSPORT: sse
      MCP_SERVER_PORT: 3000
    ports:
      - "3000:3000"
```

### Connecting via MCP Gateway

Once running in SSE mode, configure your MCP gateway to connect:

```json
{
  "mcpServers": {
    "unifi": {
      "url": "http://your-server-ip:3000/sse"
    }
  }
}
```

## Features

### Core Network Management

- **Device Management**: List, monitor, restart, locate, and upgrade UniFi devices (APs, switches, gateways)
- **Network Configuration**: Create, update, and delete networks, VLANs, and subnets with DHCP configuration
- **Client Management**: Query, block, unblock, and reconnect clients with detailed analytics
- **WiFi/SSID Management**: Create and manage wireless networks with WPA2/WPA3, guest networks, and VLAN isolation
- **Port Profile Management** (v0.2.2): Switch port configuration with PoE, VLAN trunking, 802.1X, LLDP-MED, speed/duplex
- **Device Port Overrides** (v0.2.2): Per-port configuration on individual switches with smart merge capabilities
- **Port Forwarding**: Configure port forwarding rules for external access
- **DPI Statistics**: Deep Packet Inspection analytics for bandwidth usage by application and category
- **Multi-Site Support**: Work with multiple UniFi sites seamlessly
- **Real-time Monitoring**: Access device, network, client, and WiFi statistics

### Security & Firewall (v0.2.0)

- **Firewall Rules**: Create, update, and delete firewall rules with advanced traffic filtering
- **ACL Management**: Layer 3/4 access control lists with rule ordering and priority
- **Traffic Matching Lists**: IP, MAC, domain, and port-based traffic classification
- **Zone-Based Firewall**: Modern zone-based security with zone management and zone-to-zone policies
- **RADIUS Authentication**: 802.1X authentication with RADIUS server configuration
- **Guest Portal**: Customizable captive portals with hotspot billing and voucher management

### Quality of Service (v0.2.0)

- **QoS Profiles**: Create and manage QoS profiles for traffic prioritization
- **Traffic Routes**: Time-based routing with schedules and application awareness
- **Bandwidth Management**: Upload/download limits with guaranteed minimums
- **ProAV Mode**: Professional audio/video QoS templates
- **Reference Profiles**: Built-in QoS templates for common applications

### Backup & Operations (v0.2.0)

- **Automated Backups**: Schedule backups with cron expressions
- **Backup Management**: Create, download, restore, and delete backups
- **Cloud Sync Tracking**: Monitor backup cloud synchronization status
- **Checksum Verification**: Ensure backup integrity with SHA-256 checksums
- **Multiple Backup Types**: Network configurations and full system backups

### Multi-Site Management (v0.2.0)

- **Site Provisioning**: Create, update, and delete UniFi sites
- **Site-to-Site VPN**: Configure VPN tunnels between sites
- **Device Migration**: Move devices between sites seamlessly
- **Site Health Monitoring**: Track site health scores and metrics
- **Cross-Site Analytics**: Aggregate device and client statistics across locations
- **Configuration Export**: Export site configurations for backup/documentation

### Network Topology (v0.2.0)

- **Topology Discovery**: Complete network graph with devices and clients
- **Connection Mapping**: Port-level device interconnections
- **Multi-Format Export**: JSON, GraphML (Gephi), and DOT (Graphviz) formats
- **Network Depth Analysis**: Identify network hierarchy and uplink relationships
- **Visual Coordinates**: Optional device positioning for diagrams

### Advanced Features

- **Redis Caching**: Optional Redis-based caching for improved performance (configurable TTL per resource type)
- **Webhook Support**: Real-time event processing with HMAC signature verification
- **Automatic Cache Invalidation**: Smart cache invalidation when configuration changes
- **Event Handlers**: Built-in handlers for device, client, and alert events
- **Performance Tracking**: Optional agnost.ai integration for monitoring MCP tool performance and usage analytics

### Safety & Security

- **Confirmation Required**: All mutating operations require explicit `confirm=True` flag
- **Dry-Run Mode**: Preview changes before applying them with `dry_run=True`
- **Audit Logging**: All operations logged to `audit.log` for compliance
- **Input Validation**: Comprehensive parameter validation with detailed error messages
- **Password Masking**: Sensitive data automatically masked in logs
- **Type-Safe**: Full type hints and Pydantic validation throughout
- **Security Scanners**: CodeQL, Trivy, Bandit, Safety, and detect-secrets integration

### Technical Excellence

- **Async Support**: Built with async/await for high performance and concurrency
- **MCP Protocol**: Standard Model Context Protocol for AI agent integration
- **Comprehensive Testing**: 1,236 tests with high coverage, all passing across Python 3.10–3.13
- **CI/CD Pipelines**: Automated testing, security scanning, and Docker builds (18 checks)
- **Multi-Architecture**: Docker images for amd64, arm64, arm/v7 (32-bit ARM), and arm64/v8
- **Security Hardened**: Updated critical dependencies (FastMCP, MCP SDK, cryptography)
- **Quality Metrics**: Black formatting, Ruff linting, comprehensive type hints, Pydantic validation

## Quick Start

### Prerequisites

- Python 3.10 or higher
- A UniFi account at [unifi.ui.com](https://unifi.ui.com)
- UniFi API key (obtain from Settings → Control Plane → Integrations)
- Access to UniFi Cloud API or local gateway

### Installation

#### Using PyPI (Recommended)

The UniFi MCP Server is published on PyPI and can be installed with pip or uv:

```bash
# Install from PyPI
pip install unifi-mcp-server

# Or using uv (faster)
uv pip install unifi-mcp-server

# Install specific version
pip install unifi-mcp-server==0.2.5
```

After installation, the `unifi-mcp-server` command will be available globally.

**PyPI Package**: 

#### Using Docker (Alternative)

```bash
# Pull the latest release
docker pull ghcr.io/enuno/unifi-mcp-server:0.2.5

# Multi-architecture support: amd64, arm64, arm/v7, arm64/v8
```

#### Build from Source (Development)

##### Using uv (Recommended)

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
```

#### Using pip

```bash
# Clone the repository
git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"
```

#### Using Docker Compose (Recommended for Production)

The recommended way to run the UniFi MCP Server with full monitoring capabilities:

```bash
# 1. Copy and configure environment variables
cp .env.docker.example .env
# Edit .env with your UNIFI_API_KEY and AGNOST_ORG_ID

# 2. Start all services (MCP Server + Redis + MCP Toolbox)
docker-compose up -d

# 3. Check service status
docke

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [enuno](https://github.com/enuno)
- **Source:** [enuno/unifi-mcp-server](https://github.com/enuno/unifi-mcp-server)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-enuno-unifi-mcp-server
- Seller: https://agentstack.voostack.com/s/enuno
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.