AI导哈

UniFi网络管理MCP服务

mcp-unifi 是一个面向开发者与IT运维人员的MCP服务器及LangChain工具集，提供UniFi网络控制器中设备、客户端、网络、防火墙规则和电源状态的统一管理能力，适用于网络监控、配置和自动化运维场景。

  • by lyzetam
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 lyzetam/mcp-unifi

使用说明

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

# 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

UNIFI_HOST=192.168.1.1
UNIFI_API_KEY=your_unifi_api_key_here
UNIFI_VERIFY_SSL=false

Quick Start

As MCP Server

mcp-unifi

Add to Claude Code (~/.claude.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

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

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

相关 MCP