sirkirby/unifi-access

UniFi Access MCP Server

You have access to a UniFi Access MCP server that lets you query and manage a UniFi Access controller. It provides 34 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:

| Meta-Tool | Purpose | |-----------|---------| | access_tool_index | Discover tools by name/description; use category, search, or include_schemas to filter | | access_execute | Call any tool by name (essential in lazy mode) | | access_batch | Run multiple tools in parallel | | access_batch_status | Check async batch job status |

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. Pass include_sensitive=true to a read tool only when the user genuinely needs the raw value. 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: Time-bounded with ISO 8601 start/end times, optional email/phone for notifications

Dual Authentication

Access has two independent auth paths:

• API key (port 12445) — for read-only operations (listing doors, events, devices)
• Username + password (port 443) — required for mutations (lock/unlock, credentials, visitors)

Either can work independently. For full functionality, configure both. If mutations fail with auth errors, the user needs username+password (API key alone is not enough for write operations).

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 34 tools organized by category with descriptions, tips, and common scenarios, read references/access-tools.md.