sirkirby / unifi-access

UniFi Access MCP Server

Dependencies

Requires: access
Optional: network

Verify required tools through MCP discovery before collecting data; discovery alone
does not prove controller connectivity or authorization. If a required server/tool
is missing or a required read fails, stop and report it unavailable. Optional sources
may be skipped only when the report visibly names the missing source and resulting
coverage limits. Use the product setup skill for connection help; never request secrets.

Coverage and Limitations

Every report must include a Coverage and Limitations section: name each requested
source and its status (available, unavailable, partial, or capped), requested time
window/timezone or current-state collection time, actual filters, returned counts,
limits, pagination, and any failed calls or unknown fields. Counts describe retrieved
records, not totals unless completeness is established. A successful empty query is
an observation; a failed or missing source is unavailable, never an empty result.
If a limit is reached, label the source capped unless further bounded reads establish
coverage. If completeness cannot be established, label it partial. Do not claim
complete coverage, all-clear, or overall health from unavailable, partial, or capped
data; say “No concerning activity found in the retrieved records” when appropriate.

Separate Observations (cite source/tool, record ID and timestamp when available),
Hypotheses (correlations and alternative explanations), and Identity (only
explicit source-backed credential/account attribution, with its limits). Timing,
similar names, proximity, or absence of a matching event alone proves neither
identity nor cause. A credential event identifies the recorded account, not who
physically used it. Missing mappings or clock uncertainty limit correlations.

You have access to a UniFi Access MCP server that lets you query and manage a UniFi Access controller. It provides 37 tools covering doors, locks, credentials, visitors, access policies, events, devices, and system health.

Tool Discovery

The server uses lazy loading by default — only meta-tools are registered initially:

Workflow: Call access_tool_index to find the right tool, then access_execute to call it. Use access_batch for multiple independent queries.

Safety Model

All mutations are disabled by default because Access controls physical door locks and building entry.

Read operations — always available. Listing doors, events, users, credentials — all work without permissions.

Mutations require explicit opt-in via env vars:

• UNIFI_POLICY_ACCESS_DOORS_UPDATE=true — lock/unlock doors
• UNIFI_POLICY_ACCESS_CREDENTIALS_CREATE=true — create NFC/PIN/mobile credentials
• UNIFI_POLICY_ACCESS_CREDENTIALS_DELETE=true — revoke credentials
• UNIFI_POLICY_ACCESS_VISITORS_CREATE=true — create visitor passes
• UNIFI_POLICY_ACCESS_VISITORS_DELETE=true — delete visitor passes
• UNIFI_POLICY_ACCESS_POLICIES_UPDATE=true — update access policies
• UNIFI_POLICY_ACCESS_DEVICES_UPDATE=true — reboot devices

Confirmation flow — every mutation uses preview-then-confirm:

1. Default call → returns preview of what would change
2. Call with confirm=true → executes the mutation

Door lock/unlock operations are physical real-world actions — always preview first.

Response Format

All tools return: {"success": true, "data": ...}, {"success": false, "error": "..."}, or {"success": true, "requires_confirmation": true, "preview": ...}. Always check success first.

Redacted secrets: Credential token and pin_code values come back as ***REDACTED*** by default in reads, lists, and create previews. Raw values are controlled by process policy (UNIFI_ACCESS_REDACT_SENSITIVE_FIELDS=false or global UNIFI_REDACT_SENSITIVE_FIELDS=false), not by tool arguments. Never echo ***REDACTED*** back into a create/update — it is rejected so the placeholder can't be stored as a real credential.

Key Capabilities

• Door control: access_lock_door / access_unlock_door — unlock relocks automatically after duration (default 2 seconds)
• Real-time events: access_recent_events reads from websocket buffer instantly. Event types: door_open, door_close, access_granted, access_denied, door_alarm
• Historical events: access_list_events with time/door/user filters. Topics: admin or admin_activity
• Activity summary: access_get_activity_summary aggregates events over a time period — useful for security audits
• Credentials: Create NFC ({user_id, token}), PIN ({user_id, pin_code}), or mobile ({user_id}) credentials
• Visitor passes: Developer API family with scoped UUIDs, ISO 8601 valid_from/valid_until, and optional contact/company metadata

Dual Authentication

Access has two independent auth paths:

• API key (port 12445) — official Developer API operations, including visitor list/get/create/delete
• Username + password (port 443) — proxy-backed operations such as credentials and policies

Either can work independently for its supported tools. For full functionality, configure both. Visitor auth failures require checking UNIFI_ACCESS_API_KEY; proxy-backed mutation failures require checking the local username/password.

To configure, run /unifi-access:unifi-access-setup or set env vars manually:

UNIFI_ACCESS_HOST=192.168.1.1
UNIFI_ACCESS_API_KEY=your-api-key
UNIFI_ACCESS_USERNAME=admin
UNIFI_ACCESS_PASSWORD=your-password

Other UniFi Servers

If the user also has networking or cameras, other UniFi MCP plugins are available:

• unifi-network — network devices, clients, firewall, VPN, routing
• unifi-protect — security cameras, NVR, recordings, smart detections

Access readers are network clients — if a reader appears offline, the Network server can help check connectivity via unifi_lookup_by_ip.

Tool Reference

For the complete list of all 37 tools organized by category with descriptions, tips, and common scenarios, read references/access-tools.md.