Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@UniFi Internal API MCP Server list all connected clients"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that exposes the internal UniFi Controller API — the same API the web UI uses — as tools for AI assistants.
This wraps the cookie-authenticated controller endpoints documented in the Art-of-WiFi/UniFi-API-client PHP library, providing ~170 tools for managing UniFi networks.
Full controller access: Clients, devices, WLANs, networks, firewall, statistics, events, admins, firmware, backups, DNS, RADIUS, DPI, hotspot/vouchers, and more
Cookie-based authentication: Uses the same session auth as the UniFi web UI
UniFi OS support: Works with UDM, UDR, UCG, and legacy standalone controllers
Readonly safety mode: Write operations blocked by default — enable explicitly
170+ tools across 19 categories
Related MCP server: UniFi MCP Server
Clone this repository
Copy .env.example to .env and fill in your controller details
Run: uv run unifi-internal-api-mcp
Variable | Description | Default |
| Controller URL (e.g. | required |
| Controller username | |
| Controller password | |
| Pre-authenticated TOKEN cookie (alternative to username/password) | |
| Site name |
|
| UniFi OS controller (UDM/UDR/UCG) |
|
| Block all write operations |
|
| Verify SSL certificates |
|
Option 1: Username/password — for self-hosted controllers without 2FA:
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your-passwordOption 2: Browser token — for cloud-hosted (ui.com) or 2FA-enabled controllers:
Log into your controller in a browser
Open DevTools (Cmd+Option+I) > Application > Cookies
Copy the TOKEN cookie value
UNIFI_TOKEN=eyJhbGciOiJIUzI1NiIs...The token expires after ~30 days. When using a token, the server won't log out (so your browser session stays valid).
Module | Tools | Description |
| 15 | Sysinfo, health, dashboard, settings, device states |
| 13 | Site management, settings (country, SNMP, NTP, etc.) |
| 20 | Client management, guest auth, block/unblock |
| 23 | Device adoption, restart, locate, radio settings |
| 9 | Vouchers, hotspot operators, guest login |
| 8 | WLAN configuration, MAC filters |
| 4 | Network CRUD |
| 5 | Firewall groups and rules |
| 22 | 5min/hourly/daily/monthly stats, speedtest, IPS |
| 4 | Events and alarms |
| 8 | Admin management and permissions |
| 10 | Firmware updates, rolling upgrades |
| 3 | Backup generation and export |
| 3 | DNS records (v2 API) |
| 5 | RADIUS profiles and accounts |
| 5 | Device tags |
| 5 | DPI stats, port forwarding, system log |
| 4 | User groups (bandwidth profiles) |
| 4 | AP groups (v2 API) |
Add to your MCP client config (e.g. Claude Desktop):
{
"mcpServers": {
"unifi-internal": {
"command": "uv",
"args": ["run", "--directory", "/path/to/unifi_internal_api_mcp", "unifi-internal-api-mcp"],
"env": {
"UNIFI_HOST": "https://your-controller-url",
"UNIFI_TOKEN": "eyJhbGciOiJIUzI1NiIs...",
"UNIFI_SITE": "default",
"UNIFI_READONLY": "true"
}
}
}
}Check for controller firmware updates. Returns latest known version info.
Inputs: no named parameters. Returns: result
Count alarms. Optionally count only non-archived (active) alarms.
Inputs: archived. Returns: result
Make a custom API request to the controller. Use with care.
Inputs: path (required), method, payload. Returns: result
Fetch system log entries (v2 API). Defaults to past 7 days.
Inputs: end, start, log_class, page_size, +1 more. Returns: object
Get a specific device tag by ID.
Inputs: tag_id (required). Returns: result
List active clients using the v2 API with optional traffic and device filters.
Inputs: include_traffic_usage, include_unifi_devices. Returns: result
List admins for the current site.
Inputs: no named parameters. Returns: result
Fetch alarms, optionally filtered.
Inputs: payload. Returns: result
List all admins across all sites.
Inputs: no named parameters. Returns: result
List all AP groups.
Inputs: no named parameters. Returns: result
List available auto-backups.
Inputs: no named parameters. Returns: result
List currently online (connected) clients, or fetch a single client by MAC address.
Inputs: mac. Returns: result
List offline client history using the v2 API.
Inputs: within_hours, only_non_blocked, include_unifi_devices. Returns: result
Fetch available country codes (ISO 3166-1 numeric).
Inputs: no named parameters. Returns: result
Fetch currently allowed wireless channels.
Inputs: no named parameters. Returns: result
Fetch dashboard metrics for the current site.
Inputs: five_minutes. Returns: result
Fetch device name mappings (firmware bundles). Does not require site context.
Inputs: no named parameters. Returns: object
List devices with full detail, optionally filtered by MAC address(es).
Returns comprehensive device information including model, firmware, uptime, configuration, port tables, radio tables, and statistics.
Inputs: macs. Returns: result
List all devices with basic properties only.
Returns a lightweight device list with minimal attributes such as MAC address, model, type, and name. Faster than list_devices().
Inputs: no named parameters. Returns: result
Return a mapping of device state codes to human-readable names.
Inputs: no named parameters. Returns: object
List all static DNS records.
Inputs: no named parameters. Returns: result
Fetch Deep Packet Inspection (DPI) statistics.
Inputs: no named parameters. Returns: result
Fetch filtered DPI statistics by category or application.
Inputs: dpi_type, cat_filter. Returns: result
Fetch site events, sorted by most recent first.
Inputs: limit, start, historyhours. Returns: result
Fetch VoIP extensions.
Inputs: no named parameters. Returns: result
Fetch client device fingerprint information.
Inputs: fingerprint_source. Returns: result
List firewall groups, or get a specific group by ID.
Inputs: group_id. Returns: result
List all firewall rules.
Inputs: no named parameters. Returns: result
List firmware versions available or cached on the controller.
Inputs: firmware_type. Returns: result
List guest devices seen within the specified time window.
Inputs: within. Returns: result
Fetch health metrics for the current site.
Inputs: no named parameters. Returns: result
List all hotspot operators.
Inputs: no named parameters. Returns: result
List known rogue access points.
Returns rogue APs that have been previously identified and marked as known in the controller.
Inputs: no named parameters. Returns: result
List network configurations, or get a specific network by ID.
Inputs: network_id. Returns: result
Fetch switch port configurations.
Inputs: no named parameters. Returns: result
List port forwarding rules/settings.
Inputs: no named parameters. Returns: result
Fetch port forwarding statistics.
Inputs: no named parameters. Returns: result
List all RADIUS user accounts for the current site.
Inputs: no named parameters. Returns: result
List all RADIUS profiles for the current site.
Inputs: no named parameters. Returns: result
List rogue (neighboring) access points detected by managed APs.
Returns APs seen by your network that are not part of your UniFi deployment, within the specified time window.
Inputs: within. Returns: result
Fetch static routing settings, optionally filtered by route ID.
Inputs: route_id. Returns: result
Fetch information about the currently logged-in user.
Inputs: no named parameters. Returns: result
Fetch all site configuration settings.
Inputs: no named parameters. Returns: result
List all sites managed by this UniFi controller.
Returns basic attributes for each site including _id, desc (description), and name (short name).
Inputs: no named parameters. Returns: result
List all device tags.
Inputs: no named parameters. Returns: result
List all user groups (bandwidth profiles).
Inputs: no named parameters. Returns: result
List all known client devices, including those currently offline.
Inputs: no named parameters. Returns: result
List WLAN configurations (wireless networks), or get a specific WLAN by ID.
Inputs: wlan_id. Returns: result
List WLAN groups.
Inputs: no named parameters. Returns: result
Set or update the browser TOKEN cookie for authentication.
Use this when authentication fails or no token is configured. To get the token: log into the UniFi controller in a browser, open DevTools (Cmd+Option+I) > Application > Cookies, and copy the TOKEN value.
Inputs: token (required). Returns: object
Check the state of an RF spectrum scan for an access point.
Returns the current scan progress and results if the scan has completed.
Inputs: mac (required). Returns: result
Fetch all users (wired and wireless) seen within the specified time window.
Inputs: historyhours. Returns: result
Fetch authorization records. Defaults to past 7 days.
Inputs: end, start. Returns: result
Fetch detailed statistics for a single client by MAC address.
Inputs: mac (required). Returns: result
Fetch full controller status (system information).
Inputs: no named parameters. Returns: result
Fetch IPS/IDS events. Defaults to past 24 hours.
Inputs: end, limit, start. Returns: result
Fetch hotspot payment records.
Inputs: within. Returns: result
Fetch periodic statistics for site, AP, user, or gateway.
Combines all stat report endpoints into one tool. Default time ranges: 5minutes=12h, hourly=7d, daily=52w, monthly=52w.
Inputs: entity (required), period (required), end, mac, +2 more. Returns: result
Fetch login sessions. Defaults to past 7 days.
Inputs: end, mac, start, session_type. Returns: result
Fetch statistics for all sites on this controller.
Returns detailed statistics including number of devices, clients, guests, and health information for each site.
Inputs: no named parameters. Returns: result
Fetch speed test results. Defaults to past 24 hours.
Inputs: end, start. Returns: result
Fetch latest login sessions for a single client.
Inputs: mac (required), limit. Returns: result
Fetch system information from the UniFi controller.
Inputs: no named parameters. Returns: result
List hotspot vouchers, optionally filtered by creation time.
Inputs: create_time. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 64 tools
Most tools target distinct resources (devices, clients, WLAN, firewall, etc.), but several client-related tools (list_users, list_clients, list_active_clients, list_clients_history, stat_allusers) have overlapping purposes. The descriptions help differentiate them by online/offline/v2/API filters, but there is still some potential for misselection.
The naming pattern is predominantly verb_noun with underscores (list_*, stat_*, get_*, set_*), which is consistent. However, there is a mix of 'list' and 'stat' for similar operations (e.g., list_clients vs stat_client), and some names like stat_full_status and custom_api_request deviate slightly from the convention.
With 64 tools, the server presents an overwhelming surface area. Even though the UniFi controller API is large, this many tools makes it difficult for an agent to select the right one quickly, and many tools are highly specific (e.g., list_device_name_mappings, list_country_codes). A more focused set of 20-30 tools would be more appropriate.
The tool set is extensive in read-only coverage across many domains (health, devices, clients, WLAN, firewall, stats, events). However, it lacks create/update/delete operations for most resources, which are only possible via the generic custom_api_request. This leaves a significant gap for management workflows, but the read surface is fairly complete for monitoring purposes.
Connect any AI assistant to Syncro: manage tickets, invoices, customers, assets, and more.
Discover, inspect and run 63,000+ agent tools from one balance. Pay per call, no subscriptions.
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
