mcp-unifi
MCP server and LangChain tools for UniFi Network controller management -- devices, clients, networks, and firewall rules.
Features
20 tools across 7 categories:
| Category | Tools | Description |
|---|---|---|
| Status | unifi_status |
Check controller connection and API availability |
| Sites | unifi_list_sites, unifi_get_site |
List sites, get site details and health metrics |
| Devices | unifi_list_devices, unifi_get_device, unifi_restart_device |
Manage APs, switches, and gateways |
| Clients | unifi_list_clients, unifi_get_client, unifi_block_client, unifi_unblock_client |
Monitor and control connected clients |
| Networks | unifi_list_networks, unifi_get_network, unifi_list_wlans |
View network and WLAN configurations |
| Firewall | unifi_list_firewall_rules, unifi_list_firewall_groups, unifi_list_port_forwards, unifi_list_routes |
Inspect firewall rules, groups, port forwards, and routes |
| Power | unifi_power_summary, unifi_list_pdu_outlets, unifi_list_poe_ports |
Measured watts: PDU outlets and per-port PoE |
A note on the two APIs
Everything except the Power tools speaks the modern integration API
(/proxy/network/integration/v1). That API returns no power data at all —
a device record there carries id, MAC, IP, model, firmware and ports, and no
wattage field of any kind. Per-outlet PDU watts and per-port PoE live only on
the legacy endpoint (/proxy/network/api/s/{site}/stat/device), so the Power
tools call that instead via UnifiClient.legacy_request().
UniFi never reports a switch's or gateway's own consumption — only the PoE it
hands out. Power totals are a floor, not the full rack draw.
Installation```bash
Core library
pip install .
With MCP server support
pip install ".[mcp]"
With LangChain tools
pip install ".[langchain]"
Everything
pip install ".[all]"
## Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `UNIFI_HOST` | Yes | _(empty)_ | UniFi controller hostname or IP (e.g., `192.168.1.1`) |
| `UNIFI_API_KEY` | Yes | _(empty)_ | UniFi API key |
| `UNIFI_VERIFY_SSL` | No | `false` | Verify SSL certificates (set `true` for valid certs) |
| `UNIFI_SECRET_ID` | No | _(empty)_ | AWS Secrets Manager secret holding `{host, api_key}`. Used only when `UNIFI_HOST`/`UNIFI_API_KEY` are unset, so no key needs to live in a config file. A missing or denied secret leaves the server unconfigured rather than crashing it. |
### `.env` Example```bash
UNIFI_HOST=192.168.1.1
UNIFI_API_KEY=your_unifi_api_key_here
UNIFI_VERIFY_SSL=false
Quick Start
As MCP Server```bash
mcp-unifi
Add to Claude Code (`~/.claude.json`):```json
{
"mcpServers": {
"unifi": {
"type": "stdio",
"command": "uv",
"args": ["--directory", "/path/to/mcp-unifi", "run", "mcp-unifi"],
"env": {
"UNIFI_HOST": "192.168.1.1",
"UNIFI_API_KEY": "your_api_key"
}
}
}
}
As LangChain Tools```python
from mcp_unifi.langchain_tools import TOOLS, unifi_list_devices, unifi_list_clients
Use all 17 tools with an agent
agent = create_react_agent(llm, TOOLS)
Or use individual tools
print(unifi_list_devices.invoke({"site_id": None}))
print(unifi_list_clients.invoke({"site_id": None}))
### As Python Library```python
from mcp_unifi.client import UnifiClient
from mcp_unifi.operations import devices, clients, networks
client = UnifiClient(host="192.168.1.1", api_key="your_key")
all_devices = devices.list_devices(client)
all_clients = clients.list_clients(client)
License
MIT
