UniFi Access MCP Server

What it does

UniFi Access MCP Server connects an MCP client to a self-hosted Ubiquiti UniFi Access controller. An assistant can use it to list doors and their lock state, search the event history or the live buffer the controller feeds over its websocket, and review policies, schedules, users, hardware and credentials. When changes are permitted it can also unlock or lock doors, issue or revoke NFC, PIN and mobile credentials, create or cancel visitor passes, edit policies, reboot hubs and readers, and change per-device settings such as a reader's greeting.

It lives in the sirkirby/unifi-mcp monorepo next to separate Network and Protect servers, and ships on PyPI as unifi-access-mcp and as a container on GHCR. There are two ways in. An API key reaches the official Access API on port 12445. A local admin login instead opens a session on the UniFi OS console at port 443 and proxies requests through it. Most changes need that session, while visitor passes go through the API key.

The tool manifest in the repository counts 37 tools: 31 for Access and six helpers for discovery, indirect and batch calls, loading tools on demand and building a support bundle. The tool catalog page in its docs leaves out access_get_device_configs, access_update_device_config and access_get_support_bundle. In the default lazy mode only the helpers are registered at start and the Access tools load when asked for. UNIFI_TOOL_REGISTRATION_MODE=eager registers all of them up front.

One point its docs get wrong: permissions.md says Access denies every change by default, but the shared policy gate in unifi_core/policy_gate.py allows a change when no UNIFI_POLICY_* variable is set. What holds a change back by default is the preview step, which wants a second call with confirm=true. To block changes outright, set UNIFI_ACCESS_READ_ONLY=true or a false policy gate.

What it needs

Run it with uv (for uvx) on Python 3.13 or later, or with Docker. Its docs advise a local admin or service account on the console and warn against a Ubiquiti SSO cloud account. Tracing export under uvx or pip needs the otel extra, installed as unifi-access-mcp[otel]. The Docker image already carries it.

Limits

• Limit Without a controller host it starts in setup mode, offering only the read-only access_setup_status tool and making no controller connection
• Limit Each change returns a preview first and runs on a second call with confirm=true, unless UNIFI_ACCESS_TOOL_PERMISSION_MODE is bypass
• Read only UNIFI_ACCESS_READ_ONLY=true refuses every change, and per the policy gate code any value it does not recognise also counts as on
• Not covered Visitor pass tools need the Access API key, while policy edits, credential changes, reboots and door groups need the admin session
• Size cap access_list_events returns 30 events by default and at most 5000 with limit
• Limit A door unlock lasts 2 seconds unless duration is given
• Limit Credential tokens and PIN codes come back as ***REDACTED*** unless UNIFI_ACCESS_REDACT_SENSITIVE_FIELDS=false
• Limit HTTP transport is off by default and binds to 127.0.0.1:3002, with no authentication unless UNIFI_MCP_HTTP_AUTH_TOKEN is set
• Limit It never loads a .env file, so settings must come from the client's env block, exported variables or Docker env_file
• Not covered Its README points software that integrates over HTTP to the separate unifi-api-server in the same repository instead

The permissions docs disagree with the code on the default. permissions.md says Access denies all changes until enabled, and configuration.md still prints a YAML block with create, update and delete set to false. The bundled config.yaml carries no such block, and unifi_core/policy_gate.py returns allowed when no UNIFI_POLICY_* gate is set. A fresh install therefore permits changes behind the preview and confirm step only.

Who it suits

Suits administrators of a UniFi Access site who want to audit badge events, check credentials and policies, or hand out visitor passes from an assistant, with each change shown as a preview before it runs. It runs on your own machine against your own controller, so that machine must be on, or routed to, the controller's network. It is a community project, not a Ubiquiti product. Anyone who wants it to read only should set UNIFI_ACCESS_READ_ONLY=true, since changes are open by default. For networking or cameras the same repository ships unifi-network-mcp and unifi-protect-mcp, and services that call over HTTP are pointed to unifi-api-server.