UniFi MCP

FastMCP server for local UniFi controller management. Exposes a single unifi action router and a unifi_help reference tool covering devices, clients, network configuration, and controller monitoring.

Overview

The server connects to a self-hosted UniFi controller (including UDM Pro) and proxies all operations through a single MCP tool. A unified action parameter replaces 31 individual tools while preserving every capability. Destructive operations require explicit confirmation. Bearer token auth protects the HTTP endpoint in production.

What this repository ships

• unifi_mcp/: server, client, config, formatters, models, services, resources, and tools
• skills/unifi/: client-facing skill
• docs/: API notes, action-pattern rationale, testing notes
• .claude-plugin/, .codex-plugin/, gemini-extension.json: client manifests
• docker-compose.yaml, Dockerfile: container deployment
• tests/: unit, resource, and integration tests

Tools

unifi

Single action router for all UniFi operations.

Parameters

unifi_help

Returns full markdown reference for all actions and parameters. No parameters needed.

Action Groups

Device Management

get_devices response fields per device: name, model, type (Access Point / Gateway / Switch), status (Online / Offline), ip, mac, uptime, version

restart_device example:

unifi action=restart_device mac=aa:bb:cc:dd:ee:ff confirm=true

Client Management

set_client_name / set_client_note: Both resolve the client by MAC against the controller user list (/list/user), then POST to /upd/user/{id}. Pass an empty string (name="") to remove the value.

Workflow — block a client:

# Step 1: find the MAC
unifi action=get_clients connected_only=true

# Step 2: block it
unifi action=block_client mac=aa:bb:cc:dd:ee:ff confirm=true

# Step 3: verify
unifi action=get_clients connected_only=false

Network Configuration

All network configuration actions accept site_name. get_sites does not use site_name.

Monitoring

Workflow — authorize a guest with bandwidth cap:

unifi action=authorize_guest mac=aa:bb:cc:dd:ee:ff minutes=120 down_bandwidth=5000 up_bandwidth=2000 quota=500

Workflow — view DPI stats by category:

unifi action=get_dpi_stats by_filter=by_cat site_name=default

Identity

get_user_info requires MCP OAuth (e.g. Google provider). UniFi controller credentials are separate. Returns an error if OAuth is not configured.

Destructive Operation Policy

Four actions require confirmation before executing:

Confirmation is checked in this order. The first matching rule wins:

1. UNIFI_MCP_ALLOW_DESTRUCTIVE=true — all destructive actions run without prompting (CI / automation)
2. UNIFI_MCP_ALLOW_YOLO=true — same bypass, broader semantics (skips all elicitation prompts)
3. confirm=true parameter — per-call confirmation in the tool invocation

If none of the above apply, the tool returns error: confirmation_required with instructions to add confirm=true.

Installation

Marketplace

/plugin marketplace add jmagar/claude-homelab
/plugin install unifi-mcp @jmagar-claude-homelab

Local development

uv sync
uv run python -m unifi_mcp.main

Console script entrypoints:

uv run unifi-mcp
uv run unifi-local-mcp

Docker

just up
just logs

Configuration

Copy .env.example to .env and fill in the values:

cp .env.example .env

Environment variables

UDM Pro vs traditional controller (UNIFI_IS_UDM_PRO)

UNIFI_VERIFY_SSL=false

Self-hosted controllers typically use self-signed TLS certificates. Setting UNIFI_VERIFY_SSL=false disables certificate validation so the client can connect without a CA bundle. This is the safe choice for internal-network deployments. If your controller has a certificate issued by a public CA (e.g. via Let's Encrypt), set this to true.

Multi-site support

Every action that is site-scoped accepts a site_name parameter (default: "default"). Use get_sites to list available site names. Pass the name field (not the description) as site_name.

unifi action=get_sites
# returns: name="default", name="branch-office", ...

unifi action=get_devices site_name=branch-office

Usage examples

List all connected clients

unifi action=get_clients connected_only=true

Get a device by MAC

unifi action=get_device_by_mac mac=aa:bb:cc:dd:ee:ff

Block a client

unifi action=block_client mac=aa:bb:cc:dd:ee:ff confirm=true

Unblock a client

unifi action=unblock_client mac=aa:bb:cc:dd:ee:ff

Label a client

unifi action=set_client_name mac=aa:bb:cc:dd:ee:ff name="Living Room TV"
unifi action=set_client_note mac=aa:bb:cc:dd:ee:ff note="Guest device, 2026-04"

Authorize a guest (2 hours, 5 Mbps down, 500 MB cap)

unifi action=authorize_guest mac=aa:bb:cc:dd:ee:ff minutes=120 down_bandwidth=5000 quota=500

View DPI stats

unifi action=get_dpi_stats by_filter=by_app site_name=default

Check IPS threat events

unifi action=get_ips_events limit=20 site_name=default

Check controller status

unifi action=get_controller_status

View recent speed tests

unifi action=get_speedtest_results limit=5

Get inline help

unifi_help

Development

Commands

just dev          # Start server with auto-reload
just lint         # Lint with ruff
just fmt          # Format with ruff
just typecheck    # Type-check with ty
just check        # lint + typecheck
just build        # Editable install (uv pip install -e .)
just test         # Run unit tests
just test-live    # Health check against running server
just up           # docker compose up -d
just down         # docker compose down
just logs         # Tail container logs
just health       # curl /health endpoint
just gen-token    # Generate a secure random token
just check-contract  # Lint skill/server contract
just clean        # Remove build artifacts and caches

Generate a bearer token

just gen-token
# or
openssl rand -hex 32

Verification

just lint
just typecheck
just test

For a running-server check:

just health
just test-live

Related plugins

License

MIT