mcp-server-unifi

Read-only MCP server for UniFi network analysis. Gives Claude (and other MCP clients) safe access to controller data for diagnostics, monitoring, and capacity planning.

Python 3.11+ | 19 tools | 4 resources | 6 prompts

Architecture

                  +-----------------+
                  |  Claude / MCP   |
                  |     Client      |
                  +--------+--------+
                           | stdio (JSON-RPC)
                  +--------+--------+
                  |   mcp-server-unifi     |
                  |   MCP Server    |
                  |                 |
                  | - Tools (19)    |
                  | - Resources (4) |
                  | - Prompts (6)   |
                  +--------+--------+
                           |
                  +--------+--------+
                  | Session Pool    |
                  | Circuit Breaker |
                  +--------+--------+
                           | httpx (HTTPS)
                  +--------+--------+
                  | UniFi Controller|
                  | (Network API)   |
                  +-----------------+

Mermaid source: docs/architecture.mmd

Install

uvx (recommended)

No install needed — runs directly from PyPI:

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": ["mcp-server-unifi"],
      "env": {
        "UNIFI_HOST": "https://192.168.1.1",
        "UNIFI_USER": "mcp-user",
        "UNIFI_PASS": "your-password-here",
        "UNIFI_SITE": "default",
        "UNIFI_VERIFY_SSL": "false"
      }
    }
  }
}

Add this to .mcp.json (Claude Code) or your client's MCP config. Restart the client.

pip

pip install mcp-server-unifi
mcp-server-unifi                              # start server on stdio

From source

git clone https://gitlab.com/gitlab_joel/mcp-server-unifi.git
cd mcp-server-unifi
make venv
cp .env.example .env   # fill in your credentials
make run

MCP Inspector

npx @modelcontextprotocol/inspector           # interactive testing

Configuration

All config is via environment variables — set in .env or in the env block of .mcp.json.

Recommend creating a dedicated read-only local user on the UniFi controller for the MCP server rather than using an admin account.

Tools

Devices & Topology

Clients

Wireless / RF

Events & Health

All tools return JSON. Output exceeding ~25k tokens is automatically truncated with pagination metadata.

Resources

Clients receive notifications/resources/updated when data changes. Polling interval controlled by UNIFI_POLL_INTERVAL.

Prompts

Diagnostics

troubleshoot_wifi — Diagnose WiFi issues for a specific client.

• Args: client_identifier (required), timeframe (optional, default "last 24 hours")
• Searches for client, uses elicitation if multiple match, gathers diagnostics (details, events, channel utilization), returns timeline + root cause + recommendations

incident_investigation — Correlate events with device state for incident analysis.

• Args: timeframe (optional), device_mac (optional)
• Gathers system logs, events, topology, and switch port stats. Builds chronological timeline, traces blast radius through uplink chain, identifies root cause

Assessments

deployment_assessment — Full network health assessment with structured findings.

• Args: focus (optional: "switches", "wireless", "events", or "all")
• Scans all devices, switch ports, wireless, topology, and infrastructure events. Produces a structured report with comparison anchors for delta tracking

wifi_audit — Full wireless environment audit.

• Args: none
• Scans all APs, channel utilization, rogues, client distribution, WLAN config. Returns structured findings with recommendations

Capacity Planning

capacity_report — AP load and throughput trending analysis.

• Args: hours (optional, default 24)
• Per-AP client distribution by band, hourly throughput history, channel utilization, band steering effectiveness, capacity headroom estimation

switch_health — Deep dive on switch port errors and drop rates.

• Args: switch_mac (optional — analyzes all switches if omitted)
• Per-switch port error table, drop rate computation, STP state audit, uplink chain health

Resilience

• Circuit breaker — Trips after 3 consecutive auth failures. Exponential backoff (30s → 60s → 120s → 300s max). Prevents hammering a down controller.
• Session pool — Single shared httpx session with configurable TTL (default 30 min). Auto-refreshes on expiry or 401. Avoids repeated logins.
• Login throttle — Minimum 10s between login attempts (configurable). Stays under the UniFi OS ~5 attempts/window rate limit.
• Output truncation — Binary-search truncation at ~80k chars (~20k tokens). Adds _truncated metadata with item count and guidance.

Development

git clone <repo-url> && cd mcp-server-unifi
make venv          # create venv + install dev deps
make test          # run test suite (424 tests, 89% coverage)
make lint          # ruff linter
make format        # ruff auto-format

Make Targets

Testing

424 tests across unit, protocol, and behavioral categories:

• Unit — tools, resources, prompts, circuit breaker, session pool, output truncation, progress, logging
• Protocol — MCP JSON-RPC validation through real client/server stack (initialization, capabilities, tool invocation, error handling)
• Behavioral — Tool naming conventions, JSON Schema correctness, keyword-overlap tool selection scoring, response format validation

Config: asyncio_mode = "auto" in pyproject.toml. Do not use pytestmark = pytest.mark.anyio — it conflicts with pytest-asyncio.

Project Structure

src/mcp_server_unifi/
    server.py           MCP server, tool dispatch, create_server()
    client.py           UniFi API client (httpx, auth, retry)
    tools.py            Tool implementations (formatting, logic)
    resources.py        Resource handlers + ResourcePoller
    prompts.py          Prompt templates (troubleshoot, audit)
    session_pool.py     Shared session with TTL + login throttle
    circuit_breaker.py  CircuitBreaker (closed/open/half-open)
    output.py           Output truncation (binary search)
    progress.py         Progress notification helper
    logging_handler.py  MCP logging channel

tests/
    conftest.py            Fixtures, mock UniFi client, MCP session
    test_tools.py          Tool logic
    test_resources.py      Resource handlers
    test_prompts.py        Prompt workflows
    test_mcp_protocol.py   In-process protocol validation
    test_behavioral.py     Naming, schema, selection scoring
    test_circuit_breaker.py
    test_session_pool.py
    test_client.py
    test_output.py
    test_progress.py
    test_logging_handler.py
    test_advanced.py

Known Gotchas

• Claude Code does not render progress or logging notifications — The server emits them correctly, but Claude Code's UI does not display them yet. Tracked: claude-code#4157 (progress), claude-code#3174 (logging). MCP Inspector displays both.
• UniFi OS login rate limiting — /api/auth/login allows ~5 attempts per window with a 5-10 min cooldown (HTTP 429). Cumulative across all clients. The session pool and login throttle mitigate this.
• No switch historical stats — The UniFi API has no stat/report endpoint for switches. Use unifi_switch_port_stats for real-time counters.

See IMPROVEMENTS.md for development history.