UniFi RMCP

unifi-rmcp

UniFi Network client, device, WLAN, firewall, and health operations over MCP and CLI.

It exposes one MCP tool, unifi, plus the runifi CLI. Agents can inspect clients, devices, WiFi networks, health, alarms, events, controller sysinfo, and authenticated identity, and can use generated official_* / unifi_* actions when their MCP auth scope permits it.

30-second path: set UNIFI_URL and UNIFI_API_KEY, then run npx -y @dinglebear/runifi health --json -> start loopback HTTP with UNIFI_MCP_HOST=127.0.0.1 npx -y @dinglebear/runifi serve -> call tools/call with {"action":"health"}.

Status: operational RMCP upstream-client server. The preserved convenience actions are read-oriented; generated mutating actions require unifi:admin authorization. HTTP MCP supports loopback dev mode, static bearer tokens, and Google OAuth through lab-auth.

Not for: replacing the UniFi console, storing controller credentials for callers, bypassing UniFi permissions, generic HTTP proxying, multi-tenant isolation, or passing UniFi API keys through MCP tool arguments.

Contents

• Naming
• Capabilities And Boundaries
• Install
• Quickstart
• Client Configuration
• Runtime Surfaces
• MCP Tool Reference
• CLI Reference
• Configuration
• Authentication
• Safety And Trust Model
• Architecture
• Distribution Contract
• Development
• Verification
• Deployment
• Troubleshooting
• Related Servers
• Documentation
• License

Naming

The repo and npm package use the RMCP family name, while the shipped binary uses the short Rust CLI name runifi.

Capabilities And Boundaries

• Read connected wireless and wired clients, network devices, WLAN configs, site health, active alarms, recent events, controller sysinfo, and current authenticated user.
• Dispatch generated official_* actions for documented Network Integration API endpoints.
• Dispatch model-backed unifi_* internal controller actions and hybrid aliases such as list_clients, list_devices, list_networks, list_wifi, and get_system_info.
• Enforce unifi:read for read actions and unifi:admin for mutating actions in mounted HTTP MCP mode.
• Provide setup, doctor, and endpoint-verification commands for local runtime checks.

Install

npm / npx

Run the stdio MCP server or CLI without a manual binary install:

npx -y @dinglebear/runifi --help

npx -y @dinglebear/runifi mcp npx -y @dinglebear/runifi health --json

The npm package downloads runifi during postinstall. Override download behavior only when testing packaging:

Build From Source

git clone git@github.com:dinglebear-ai/runifi.git

cd runifi cargo build --release ./target/release/runifi --help

Minimum supported Rust version: 1.86. The Cargo workspace has three members: the root unifi-rmcp package, crates/unifi (reusable core), and xtask (dev tooling). All members inherit Rust edition 2024 and MSRV 1.97.1 from the workspace root.

Quickstart

1. Create A UniFi API Key

In UniFi OS, go to Settings -> Admins & Users -> API Keys, create a key, and copy it into UNIFI_API_KEY.

2. Configure The Controller

export UNIFI_URL=https://unifi.local

export UNIFI_API_KEY=... export UNIFI_SITE=default export UNIFI_SKIP_TLS_VERIFY=true

Set UNIFI_LEGACY=true only for older non-UDM controllers that do not use the /proxy/network path prefix.

3. Run A Safe CLI Call

npx -y @dinglebear/runifi health --json

4. Start Loopback HTTP MCP

UNIFI_MCP_HOST=127.0.0.1 npx -y @dinglebear/runifi serve

In another shell:

curl -sf http://127.0.0.1:40030/health

5. Make A First MCP Call

curl -s -X POST http://127.0.0.1:40030/mcp \

-H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"unifi","arguments":{"action":"health"}}}'

Client Configuration

Claude Code Stdio

{

"mcpServers": { "unifi": { "command": "npx", "args": ["-y", "unifi-rmcp", "mcp"], "env": { "UNIFI_URL": "https://unifi.local", "UNIFI_API_KEY": "...", "UNIFI_SITE": "default", "UNIFI_SKIP_TLS_VERIFY": "true" } } } }

Claude Code HTTP

{

"mcpServers": { "unifi": { "type": "http", "url": "http://127.0.0.1:40030/mcp", "headers": { "Authorization": "Bearer ${UNIFI_MCP_TOKEN}" } } } }

Codex / Labby Gateway

Register UniFi through Labby as an HTTP upstream when sharing one long-running server, or run it directly as stdio for local-only use.

[mcp_servers.unifi]

command = "npx" args = ["-y", "unifi-rmcp", "mcp"]

Generic MCP JSON

{

"command": "runifi", "args": ["mcp"], "env": { "UNIFI_URL": "https://unifi.local", "UNIFI_API_KEY": "..." } }

Do not put UNIFI_API_KEY, OAuth secrets, passwords, SSH keys, or upstream bearer tokens in MCP tool arguments. Use env, config files, or the MCP client's secret storage. MCP callers never provide credentials, tokens, keys, or secrets as action arguments.

Runtime Surfaces

MCP Tool Reference

One MCP tool is exposed: unifi. Pass the required action argument to select the operation. The action enum is generated from the inventories in data/, so the surface is large:

Counts are derived from data/unifi_official_network_v10_3_58.json and the runtime: true entries of data/unifi_internal_endpoint_models.json. crates/unifi/src/capabilities.rs is the source of truth at runtime.

Preserved Convenience Actions

Generated Action Families

Endpoint coverage is tracked in docs/unifi_api_coverage.md; contract and safe live verification are documented in docs/unifi_endpoint_verification.md.

CLI Reference

The binary calls the same service layer as the MCP tool:

runifi clients [--json]

runifi devices [--json] runifi wlans [--json] runifi health [--json] runifi alarms [--json] runifi events [--limit N] [--json] runifi sysinfo [--json] runifi me [--json] runifi official_list_clients --param siteId= --json runifi official_create_network --param siteId= --body-json '{"name":"IoT"}' --json runifi list_clients --param siteId= --json runifi doctor [--json] runifi setup check [--json] runifi setup repair [--json] runifi setup install [--json] runifi setup plugin-hook [--no-repair] [--json]

Generated actions accept --param k=v, --body-json JSON, and --json.

setup plugin-hook maps CLAUDE_PLUGIN_OPTION_* env vars into UNIFI_*, refreshes the ~/.local/bin copy of the binary, and runs check + repair. It used to run automatically from a Claude Code SessionStart/ConfigChange hook; those hooks have been removed.

You do not need to run it to configure the plugin: plugins/unifi/.mcp.json maps your plugin settings into the server's environment directly via ${user_config.*}. Run it by hand only when you want the ~/.local/bin binary refresh or the preflight checks.

Configuration

Configuration loads from config.toml first, then UNIFI_* environment variables override it. Host install