Unifi MCP (Abl030)

UniFi MCP服务器

MCP（模型上下文协议）服务器，使AI代理能够完全控制Ubiquiti UniFi网络基础设施。 286工具 涵盖网络、防火墙规则、交换机端口、WiFi、客户端、设备命令、热点管理、DPI、站点设置等。

整个项目——生成器、服务器、测试套件和此README——由AI（Claude）构建，旨在供AI代理安装和使用。

安装此MCP服务器

选项1：镍片（推荐）

这个回购是Nix薄片。将其作为输入添加到NixOS配置或任何flake中，您将得到一个自包含的 unifi-mcp 二进制文件，所有依赖项都捆绑在一起。更新是单一的 nix flake update.

添加到您的薄片输入中：

# flake.nix
{
  inputs = {
    unifi-mcp.url = "github:abl030/unifi-mcp";
  };
}

使用软件包：

# The binary is at: inputs.unifi-mcp.packages.${system}.default
# It provides: unifi-mcp (runs fastmcp with the server)

# Example: add to systemPackages
environment.systemPackages = [ inputs.unifi-mcp.packages.${pkgs.system}.default ];

# Example: use in an MCP server config
{
  command = "${inputs.unifi-mcp.packages.${pkgs.system}.default}/bin/unifi-mcp";
  env = {
    UNIFI_HOST = "192.168.1.1";
    UNIFI_USERNAME = "admin";
    UNIFI_PASSWORD = "your-password";
  };
}

无需安装即可快速测试：

UNIFI_HOST=192.168.1.1 UNIFI_PASSWORD=secret nix run github:abl030/unifi-mcp

本地构建：

nix build github:abl030/unifi-mcp
./result/bin/unifi-mcp  # starts the MCP server on stdio

选项2:uv（非Nix）

git clone https://github.com/abl030/unifi-mcp.git
cd unifi-mcp
uv sync
uv run python generate.py

这产生 generated/server.py --配备286个工具的MCP服务器。

配置您的MCP客户端

克劳德代码 (claude mcp add):

# Nix — uses the flake binary directly
claude mcp add unifi -- \
  env UNIFI_HOST=YOUR_CONTROLLER_IP \
  UNIFI_PORT=8443 \
  UNIFI_USERNAME=admin \
  UNIFI_PASSWORD=YOUR_PASSWORD \
  UNIFI_SITE=default \
  unifi-mcp

# Non-Nix — uses uv to run
claude mcp add unifi -- \
  env UNIFI_HOST=YOUR_CONTROLLER_IP \
  UNIFI_PORT=8443 \
  UNIFI_USERNAME=admin \
  UNIFI_PASSWORD=YOUR_PASSWORD \
  UNIFI_SITE=default \
  uv run --directory /path/to/unifi-mcp fastmcp run generated/server.py

克劳德桌面 (claude_desktop_config.json):

{
  "mcpServers": {
    "unifi": {
      "command": "unifi-mcp",
      "env": {
        "UNIFI_HOST": "YOUR_CONTROLLER_IP",
        "UNIFI_PORT": "8443",
        "UNIFI_USERNAME": "admin",
        "UNIFI_PASSWORD": "YOUR_PASSWORD",
        "UNIFI_SITE": "default"
      }
    }
  }
}

环境变量

模块切换(UNIFI_MODULES)

控制在运行时注册哪些工具组。使用细粒度模块只加载您需要的内容，从而降低LLM的噪音。

捷径 （向后兼容）：

细粒度模块 （混合搭配）：

上述工具计数包括每个模块的v1和v2工具。全球工具（11： status, self, sites等等。 + report_issue + get_overview + search_tools)无论此设置如何，始终都会注册。

示例：管理交换机和AP的独立控制器：

UNIFI_MODULES=device,client,wifi,network,monitor  # 124 tools instead of 286

无需再生——只需设置env变量即可。

只读模式(UNIFI_READ_ONLY)

集 UNIFI_READ_ONLY=true 在注册时删除所有变异工具。仅注册了列表、获取和统计工具，MCP工具列表中不存在创建、更新、删除、重新启动、重新引导或任何其他状态更改操作。

作曲与 UNIFI_MODULES --两个过滤器独立应用。只读模式在工具注册时强制执行，而不是在运行时：MCP工具列表中不存在变异工具，因此即使有指示，LLM也无法调用它们。

您将获得：285个工具

网络配置（CRUD——每个工具5个）

热点和访客管理（CRUD）

现场测绘和空间（CRUD）

DPI和网络智能（CRUD）

只读资源（每个工具1个）

设置（3个工具）

设备监控（39个统计工具）

设备命令（28个devmgr命令）

客户端命令（7个stamgr命令）

站点和管理（14个sitemgr命令）

备份和系统（8个命令）

报警和事件管理

v2 API（15个工具）

全球&特别

安全：确认门

所有突变工具（创建、更新、删除、设备命令）都需要 confirm=True没有它，他们就会返回一个模拟预览，预测会发生什么变化。这可以防止意外修改。

# Without confirm — returns preview only
unifi_create_network(name="Guest VLAN", purpose="vlan-only", vlan=100)

# With confirm — actually creates the network
unifi_create_network(name="Guest VLAN", purpose="vlan-only", vlan=100, confirm=True)

错误报告

每个工具的docstring都包含一个轻推： *如果此工具返回意外错误，请调用unifi_report_issue进行报告* 这 unifi_report_issue 该工具编写了一个现成的粘贴工具 gh issue create 命令中包含工具名称、错误消息、使用的参数和可选注释。它不进行HTTP调用，只返回一个用户可以查看和运行的命令字符串。

这意味着使用此MCP服务器的LLM代理在遇到意外错误时会自动建议提交错误报告，从而创建从生产使用到维护人员的反馈循环。

响应格式

所有工具都返回结构化JSON。列表工具返回：

{"summary": "Found 5 networks", "count": 5, "data": [{...}, ...]}

单件工具退货：

{"data": {"_id": "abc123", "name": "My Network", ...}}

这种格式是机器可解析的——不再有双重编码的JSON侧字符串响应。

秘密行动

默认情况下(UNIFI_REDACT_SECRETS=true)，敏感字段替换为 ` 在所有回复中。这可以防止WiFi密码、密码和其他秘密泄露到LLM上下文窗口中。修改后的字段包括 x_passphrase, x_password, x_shadow, x_private_key，以及包含以下内容的任何字段 password, passphrase, secret，或 preshared_key.Set UNIFI_REDACT_SECRETS=false` 以获得原始值。

分页和字段选择

所有列表工具都接受三个可选参数：

当 fields 被指定， _id 始终包含以供参考。这是客户端过滤——从控制器获取完整的数据集，然后切片。对于大型部署，请使用 limit 和 offset 在不压倒法学硕士背景的情况下浏览结果。

# Get just names and subnets of the first 5 networks
unifi_list_networks(limit=5, fields="name,ip_subnet,vlan")

运作原理

此回购包含 发电机 其读取API规范并产生MCP服务器。您不需要了解生成器就可以使用服务器——只需运行 generate.py 一次。

为什么是发电机？

UniFi API没有官方的OpenAPI规范。我们没有手工编写285个工具函数，而是建立了一个多阶段发现管道，从实时控制器捕获真实的API表面，然后自动生成服务器。当Ubiquiti更新他们的API时，重新运行管道并重新生成。

建筑

spec/
  endpoint-inventory.json   # API surface: 196 endpoints from real controller
  probe-spec.json           # Declarative endpoint list for probe
  field-inventory.json      # Field names from production controller
  api-samples/              # 120+ real (scrubbed) JSON responses for schema inference
generate.py                 # Entry point: load -> infer -> render -> write
generator/
  loader.py                 # Parse spec/ data into structured types
  schema_inference.py       # JSON values -> Python types + enum detection
  naming.py                 # Tool names, command mappings, test payloads
  context_builder.py        # Assemble Jinja2 template context
templates/
  server.py.j2              # FastMCP server template (286 tools)
  conftest.py.j2            # Pytest fixtures
  test_rest.py.j2           # Per-resource CRUD lifecycle tests
  test_stat.py.j2           # Stat endpoint tests
  test_cmd.py.j2            # Command tests
  test_v2.py.j2             # v2 endpoint tests
  test_global.py.j2         # Global endpoint tests
generated/                  # OUTPUT — never hand-edit
  server.py                 # The MCP server (this is what you run)
  conftest.py               # Test fixtures
  tests/                    # 44 test files

关键规则： 生成的代码 generated/ 从未经过手工编辑。如果输出有错误，请修复生成器模板或模块并重新运行。

MCP服务器内部

生成的 server.py 包括：

• 异步httpx客户端，具有基于cookie的身份验证和CSRF令牌处理
• 自动重新登录401个响应
• UniFi操作系统支持（手柄 /proxy/network 自动前缀）
• 结构化错误处理——解析 meta.rc / meta.msg 来自API响应
• 站点感知——env-var中的默认站点，每个工具覆盖可用
• 具有字段类型、枚举值和工具之间交叉引用的丰富文档字符串

API发现管道

286工具来自一个针对真正的UniFi网络控制器v10.0.162运行的三阶段端点发现过程：

第一阶段：自动探头(probe.py)

一个单文件Python脚本，使用安全的HTTP方法系统地命中每个已知的端点路径，并记录状态代码、示例响应和字段模式。

# Full automated cycle (Docker container + probe + teardown):
scripts/run_probe.sh

# Manual probe against a running controller:
uv run python probe.py --host HOST --no-verify-ssl

# Dry run — preview what would be probed:
uv run python probe.py --dry-run

安全规则是硬编码的：永远不要对 rest/，从不执行不安全的命令，从不点击 system/reboot 或 poweroff.所有敏感字段(x_password, x_passphrase, x_shadow, x_private_key等）被擦洗 "REDACTED" 在将样本写入磁盘之前。

第二阶段：LLM动力发现(llm-probe/)

在自动探测期间返回404或400的端点通过以下方式馈送给Claude claude -p （克劳德代码CLI）。对于每个端点，Claude都会分析HTTP方法、请求体或路径变化可能适用的原因，然后使用 curl 对抗实时控制器。

# Probe all 400-status endpoints:
python llm-probe/llm_probe.py --host localhost --port 8443 \
    --username admin --password testpassword123 \
    --no-verify-ssl --only-category 400

# Probe 404 endpoints:
python llm-probe/llm_probe.py --only-category 404 ...

该阶段发现了44个额外的工作端点，包括：

• 全部28 set/setting/* 端点（仅限PUT，与配对 get/setting/* 阅读）
• stat/session （需要带日期范围正文的POST）
• upd/user 和 upd/device （用于更新资源的PUT端点）
• group/user （批量用户组分配）
• WebSocket事件流在 /wss/s/{site}/events

第三阶段：发电机(generate.py)

生成器读取发现的资源清册，并使用完整的CRUD工具、统计查询、命令包装器和v2 API工具生成MCP服务器，所有这些工具都具有从真实API响应样本推断的正确参数类型。

uv run python generate.py         # Generate server + tests
uv run python count_tools.py      # Verify tool counts match

验证

$ uv run python count_tools.py
TOOL COUNTS (computed from spec)
  REST tools:          154
  Stat tools:          39
  Cmd tools:           66
  v2 tools:            15
  Global tools:        8
  Port override:       1
  Report issue:        1
  Overview:            1
  Search tools:        1
  TOTAL tools:         286

VERIFICATION
  Computed from spec:  286
  Actual in server.py: 286
  ✓ MATCH

运行测试套件

该测试套件在Docker中针对真实的UniFi控制器运行。44个测试文件，所有验证测试均通过。

# Start ephemeral controller
docker compose -f docker-compose.test.yml up -d

# Wait for it to be healthy (~60-90s), then run tests
uv run pytest generated/tests/ -v

# Tear down
docker compose -f docker-compose.test.yml down -v

模块切换测试（无需控制器）

test_modules_toggle.py 验证每个 UNIFI_MODULES 配置会加载正确的工具。所有预期值均为 自动衍生 从 spec/endpoint-inventory.json + generator/naming.py --零硬编码数字。当API表面发生变化时，这些测试将自动适应。

uv run --extra test python -m pytest test_modules_toggle.py -v   # 62 tests

它涵盖了什么（62项测试）：

• 每种配置的工具计数： v1,v2, v1, v2、空白、空格、9个子模块中的每一个单独、所有模块组合、多模块组合、， v2+module
• 工具存在：始终在线，工具无处不在，每个模块的工具在加载时都存在
• 互斥性：加载一个模块不会泄露其他模块的工具
• v2双防护：v2工具可通过其父子模块和 v2 旗帜
• 任何配置中都没有重复项
• 仅设备模块中的端口覆盖
• 只读模式：正确计数 v1,v2, v1, v2，空，每个子模块，组合
• 只读安全：没有突变工具，没有 confirm 参数工具，保留始终打开的只读工具

测试原理

测试在没有采用设备的控制器上运行。我们不是跳过需要硬件的测试，而是断言正确的错误响应——证明端点是可访问的，正确验证输入，并返回正确的错误。一个断言“此端点为虚拟MAC返回400个未知设备”的测试证明该端点与快乐路径测试一样有效。有关详细信息，请参阅测试模板。

控制器引导

UniFi控制器没有安装向导API。测试工具将管理员用户直接植入嵌入式MongoDB(ace 数据库）通过 docker exec.密码哈希使用 openssl passwd -6 容器内部（Python 3.13删除了 crypt 模块）。这是完全自动化的 conftest.py.

QA覆盖范围

所有286个工具都使用基于LLM的库测试器在Docker中运行的实时UniFi v10.0.162控制器上进行了测试（Claude担任QA工程师，31个任务，在5个修复冲刺中调用498多个工具）。

“第一次尝试就成功了” 是关键的QA指标。每个工具在第一次调用时都经过验证，参数正确——没有重试、没有参数猜测、没有错误和重试循环。这很重要，因为第一次尝试失败的MCP工具浪费了令牌、上下文窗口和用户时间，因为LLM必须诊断错误并重试。首先尝试的工具意味着文档字符串、参数类型和枚举值都足够正确，LLM可以在没有先前经验的情况下成功调用它。

覆盖范围摘要

跳过的命令（未生成）

跳过REST操作

未经测试（需要硬件或外部服务）

这些工具存在并生成，但如果没有采用UniFi设备或外部基础设施，就无法完全使用：

依赖硬件（23种工具） --需要采用AP、交换机或网关：

• 设备命令： adopt_device, restart_device, force_provision_device, locate_device, unlocate_device, upgrade_device, upgrade_device_external, migrate_device, cancel_migrate_device, spectrum_scan, move_device, delete_device, rename_device, power_cycle_port
• 客户端命令： kick_client, reconnect_client （需要连接的无线客户端）
• 热点命令： hotspot_authorize_guest, extend_guest_validity （需要热点门户）
• 防火墙： create_firewall_policy （需要网关+区域）
• 交通： update_traffic_route （需要网关）
• 其他： set_site_leds （需要支持LED的设备）， set_port_override （需要采用开关）

独立控制器限制（5个工具） --在UniFi操作系统上工作，但不能独立使用Docker：

• delete_site --无论管理员权限如何，都返回NoPermission
• generate_backup, generate_backup_site --独立cmd/backup中不存在备份生成命令

API限制（3个工具） --需要外部基础设施：

• create_hotspot_package --需要支付网关配置
• create_dhcp_option --需要DHCP网关设备
• revoke_voucher --需要热点门户基础设施

破坏性（3个工具） --故意不测试：

• logout, system_poweroff, system_reboot

致谢

API端点清单是从多个社区来源构建的。UniFi API未经Ubiquiti记录，我们所知道的一切都来自社区的反向引擎工作：

• 非加油员/非加油员 （以前称为unifi poller）--统计、异常、IPS/IDS事件和DPI数据收集的端点路径。
• py unifi --Python UniFi客户端，具有OpenAPI规范贡献，有助于发现REST端点，如 dhcpoption, heatmap, heatmappoint, spatialrecord, dpiapp，以及 dpigroup.
• aiounifi --用于家庭助理UniFi集成的异步Python客户端。为DPI组、设备管理和v2 API路径提供了端点提示。
• **** Jacob Alberty——用于在Docker中运行临时测试控制器。

所有社区发现的端点都使用我们的自动探针和LLM探针管道与真实的v10.0.162独立控制器进行了验证。无法确认的端点被排除在外（参见 CLAUDE.md 对于完整的NOT_FOUND/UNCERTAIN表）。

该项目100%由人工智能生成

这个存储库中的每个文件都是由Claude（Anthropic）编写的。生成器、模板、测试套件、探测脚本、LLM发现工具、这个README——所有这些。没有人编写任何代码。

该项目专为AI到AI的使用而设计：AI代理生成服务器，AI代理通过MCP使用它来管理UniFi网络基础设施。人类也受到欢迎。

依赖项

Nix用户： nix run github:abl030/unifi-mcp --所有东西都捆绑在一起，不需要其他deps。

非Nix用户：

• Python 3.11+
• 紫外线 用于包管理
• fastmcp、httpx、jinja2（由自动安装 uv sync)
• Docker（仅用于运行测试套件）

许可证

麻省理工学院