Skip to main content
Glama
jmagar

UniFi MCP

by jmagar
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

UniFi MCP

PyPI ghcr.io

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

Parameter

Type

Required

Default

Description

action

string

yes

—

Action to perform (see below)

site_name

string

no

"default"

UniFi site name. Ignored by get_sites, get_controller_status, get_user_info

mac

string

no

null

Device or client MAC address (any format: aa:bb:cc, AA-BB-CC, aabb.cc)

limit

int

no

varies

Maximum results to return

connected_only

bool

no

true

get_clients: return only currently connected clients

active_only

bool

no

true

get_alarms: return only unarchived alarms

by_filter

string

no

"by_app"

get_dpi_stats: "by_app" or "by_cat"

name

string

no

null

set_client_name: new display name (empty string removes it)

note

string

no

null

set_client_note: note text (empty string removes it)

minutes

int

no

480

authorize_guest: access duration in minutes

up_bandwidth

int

no

null

authorize_guest: upload limit in Kbps

down_bandwidth

int

no

null

authorize_guest: download limit in Kbps

quota

int

no

null

authorize_guest: data quota in MB

confirm

bool

no

null

Set to true to confirm destructive operations

unifi_help

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

Action Groups

Device Management

Action

MAC Required

Description

get_devices

no

List all devices on a site with status, model, IP, and uptime

get_device_by_mac

yes

Get full details for one device by MAC

restart_device

yes

Destructive — reboot the device

locate_device

yes

Activate the locate LED on the device

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

Action

MAC Required

Description

get_clients

no

List clients. connected_only=true (default) filters offline entries

reconnect_client

yes

Destructive — force a client to reconnect (kick-sta)

block_client

yes

Destructive — block a client from network access

unblock_client

yes

Re-allow a previously blocked client

forget_client

yes

Destructive — remove all historical data for a client (GDPR)

set_client_name

yes

Set or update the display alias for a client

set_client_note

yes

Set or update the note for a client

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

Action

Description

get_sites

List all sites on the controller with health info

get_wlan_configs

WLAN profiles: SSID, security, VLAN, guest flag, band steering

get_network_configs

Network/VLAN configs: subnet, DHCP range, purpose, guest flag

get_port_configs

Switch port profiles: native VLAN, tagged VLANs, PoE mode, port security

get_port_forwarding_rules

Port forwarding rules: protocol, external port, internal IP/port

get_firewall_rules

Firewall rules: action, protocol, source/destination, ruleset, index

get_firewall_groups

Firewall groups: type, member IPs or MACs, member count

get_static_routes

Static routes: destination network, gateway (nexthop), distance, interface

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

Monitoring

Action

Key Parameters

Description

get_controller_status

—

Controller version and up/down status

get_events

limit (default 100), site_name

Recent controller events sorted newest-first. On UDM Pro tries the v2 API (/proxy/network/v2/api/site/{site}/events) then falls back to /stat/event. Returns an informative error if the firmware has removed the legacy endpoint.

get_alarms

active_only (default true), site_name

Active or all alarms. Severity comes from catname.

get_dpi_stats

by_filter (default "by_app"), site_name

Deep Packet Inspection usage by application or category. Bandwidth values are in bytes (raw) in the structured response; the text summary formats them as human-readable (KB / MB / GB).

get_rogue_aps

limit (default 20, max 50), site_name

Detected foreign APs sorted by signal strength. Threat level: High > -60 dBm, Medium > -80 dBm, Low otherwise.

start_spectrum_scan

mac (AP), site_name

Trigger an RF spectrum scan on an access point.

get_spectrum_scan_state

mac (AP), site_name

Poll scan state and results for an AP.

authorize_guest

mac, minutes, up_bandwidth, down_bandwidth, quota, site_name

Grant a guest client timed network access. up_bandwidth / down_bandwidth are in Kbps. quota is in MB (converted to bytes before sending). Default duration is 480 minutes (8 hours).

get_speedtest_results

limit (default 20), site_name

Historical speed tests from the last 30 days. Download/upload fields are in Mbps; latency and jitter in ms.

get_ips_events

limit (default 50), site_name

IPS/IDS threat events from the last 7 days: source/destination IP, protocol, signature, category, severity, action.

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

Action

Description

get_user_info

Return the MCP OAuth token claims (email, name, picture, expiry)

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:

Action

What it does

restart_device

Reboots the device — causes brief network outage

block_client

Denies network access to the client

reconnect_client

Forces disconnect/reconnect (kick-sta)

forget_client

Permanently removes all historical data for the client

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

Variable

Required

Default

Description

UNIFI_URL

yes

—

Controller URL, e.g. https://192.168.1.1:443. No trailing slash. UNIFI_CONTROLLER_URL accepted as legacy fallback.

UNIFI_USERNAME

yes

—

Controller admin username

UNIFI_PASSWORD

yes

—

Controller admin password

UNIFI_IS_UDM_PRO

no

true

Set to true for UDM Pro / UniFi OS controllers. Changes the API base path and auth flow (see below).

UNIFI_VERIFY_SSL

no

false

Set to true to verify TLS certificates. Most self-hosted controllers use self-signed certs; leave false unless you have a valid cert.

UNIFI_MCP_HOST

no

0.0.0.0

Server bind address

UNIFI_MCP_PORT

no

8001

Server port. UNIFI_LOCAL_MCP_PORT is a legacy fallback.

UNIFI_MCP_TRANSPORT

no

http

"http" or "stdio"

UNIFI_MCP_TOKEN

no*

—

Bearer token for HTTP auth. Generate with openssl rand -hex 32. *Required unless UNIFI_MCP_NO_AUTH=true.

UNIFI_MCP_NO_AUTH

no

false

Disable Bearer auth (use only behind a trusted reverse proxy)

UNIFI_MCP_LOG_LEVEL

no

INFO

Log verbosity: DEBUG, INFO, WARNING, ERROR

UNIFI_MCP_LOG_FILE

no

/tmp/unifi-mcp.log

Log file path. File is cleared when it reaches 10 MB.

UNIFI_MCP_ALLOW_DESTRUCTIVE

no

false

Skip confirmation for all destructive actions

UNIFI_MCP_ALLOW_YOLO

no

false

Skip all elicitation prompts including destructive confirmation

PUID / PGID

no

1000 / 1000

UID/GID for Docker container process

DOCKER_NETWORK

no

jakenet

Docker network name

UDM Pro vs traditional controller (UNIFI_IS_UDM_PRO)

UDM Pro (true)

Traditional (false)

API base path

/proxy/network/api

/api

Login endpoint

/api/auth/login

{api_base}/login

CSRF token

Extracted from JWT TOKEN cookie and sent as X-CSRF-Token

Not required

Events API

Tries v2 (/proxy/network/v2/api/site/{site}/events) first

Legacy /stat/event only

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

Plugin

Category

Description

homelab-core

core

Core agents, commands, skills, and setup/health workflows for homelab management.

overseerr-mcp

media

Search movies and TV shows, submit requests, and monitor failed requests via Overseerr.

unraid-mcp

infrastructure

Query, monitor, and manage Unraid servers: Docker, VMs, array, parity, and live telemetry.

gotify-mcp

utilities

Send and manage push notifications via a self-hosted Gotify server.

swag-mcp

infrastructure

Create, edit, and manage SWAG nginx reverse proxy configurations.

synapse-mcp

infrastructure

Docker management (Flux) and SSH remote operations (Scout) across homelab hosts.

arcane-mcp

infrastructure

Manage Docker environments, containers, images, volumes, networks, and GitOps via Arcane.

syslog-mcp

infrastructure

Receive, index, and search syslog streams from all homelab hosts via SQLite FTS5.

plugin-lab

dev-tools

Scaffold, review, align, and deploy homelab MCP plugins with agents and canonical templates.

License

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jmagar/unifi-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server