AI导哈

UniFi控制器MCP服务器

为UniFi网络控制器提供Model Context Protocol (MCP)接口的服务，支持AI助手和其他MCP客户端与UniFi基础设施交互。

  • by claytono
  • Go
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 claytono/go-unifi-mcp

使用说明

去unifimcp

UniFi网络控制器的模型上下文协议（MCP）服务器，用 去吧。

概述

go-unifi-mcp 为UniFi网络控制器提供MCP接口，启用 AI助手和其他MCP客户端与您的UniFi基础设施进行交互。

为什么存在

我找不到同时支持v1和v2防火墙规则的MCP服务器 IPv6，所以我建了一个。这包装了go-unifi库（我从我的 Terraform提供商经验），并依赖于其生成的API表面。这 服务器是根据控制器自己的API定义生成的，这使得它 随着UniFi的发展，更容易保持工具覆盖率的最新状态。

UniFi控制器版本控制

此项目针对由以下内容固定的相同UniFi控制器版本生成工具 去unifi。当go-unifi更新其支持的控制器版本时，我们会重新生成 我们的字段定义和工具元数据要匹配。我们支持相同的控制器 范围；看到他们的 控制器支持范围.

安装

二进制（GitHub发布）

从下载预构建的二进制文件 发布页面。二进制文件是 适用于macOS和Linux（amd64/arm64）。

# macOS (Apple Silicon)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_darwin_arm64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_darwin_amd64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

# Linux (amd64)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_linux_amd64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

# Linux (arm64)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_linux_arm64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

家酿

可从 粘土/自制水龙头 点击：

brew install claytono/tap/go-unifi-mcp

尼克斯

# Run without installing
nix run github:claytono/go-unifi-mcp

# Install to your profile
nix profile install github:claytono/go-unifi-mcp

码头工人

多架构映像（amd64/arm64）发布到GitHub容器 注册表。

# Latest (pinned to most recent release, rebuilt on base image updates)
docker pull ghcr.io/claytono/go-unifi-mcp:latest

# Edge (built from main on every merge, unstable)
docker pull ghcr.io/claytono/go-unifi-mcp:edge

去安装

go install github.com/claytono/go-unifi-mcp/cmd/go-unifi-mcp@latest

配置

UniFi凭据

服务器需要访问UniFi网络控制器。双重身份验证 支持以下方法：

  1. API密钥 （首选）：在UniFi控制器中创建一个API密钥 设置>控制平面>集成。集 UNIFI_HOST 和 UNIFI_API_KEY.

  2. 用户名/密码：使用本地管理员帐户。集 UNIFI_HOST, UNIFI_USERNAME，以及 UNIFI_PASSWORD.

Claude 桌面版

添加到您的 claude_desktop_config.json:

使用二进制：

{
  "mcpServers": {
    "unifi": {
      "command": "/usr/local/bin/go-unifi-mcp",
      "env": {
        "UNIFI_HOST": "https://your-controller:443",
        "UNIFI_API_KEY": "your-api-key"
      }
    }
  }
}

使用Docker：

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "UNIFI_HOST",
        "-e",
        "UNIFI_API_KEY",
        "ghcr.io/claytono/go-unifi-mcp:latest"
      ],
      "env": {
        "UNIFI_HOST": "https://your-controller:443",
        "UNIFI_API_KEY": "your-api-key"
      }
    }
  }
}

Claude 代码

claude mcp add unifi -- go-unifi-mcp

然后在运行之前在shell中设置所需的环境变量 claude.

环境变量

变量 必填 默认 描述
UNIFI_HOST 是 -- UniFi控制器URL
UNIFI_API_KEY * - neneneba API密钥（首选身份验证方法）
UNIFI_USERNAME * -- 密码验证的用户名
UNIFI_PASSWORD * -- 密码验证密码
UNIFI_SITE 没有 default UniFi站点名称
UNIFI_VERIFY_SSL 没有 true 是否验证SSL证书
UNIFI_LOG_LEVEL 没有 error 转到unifi客户端日志级别
UNIFI_TOOL_MODE 没有 lazy 刀具注册模式

*要么 UNIFI_API_KEY 或两者 UNIFI_USERNAME 和 UNIFI_PASSWORD 必须 集。

日志级别

这 UNIFI_LOG_LEVEL 变量控制底层gounifi的日志记录 客户端库。默认值为 error 因为客户端以其他方式发出INFO 向stderr发送消息，这可能会干扰解析JSON的mcp-cli等工具 在stdout/stderr上。

级别 描述
disabled 无日志记录
trace 最冗长，包括电线细节
debug 调试消息
info 信息性消息
warn 仅警告
error 仅错误（默认）

工具模式

服务器支持两种工具注册模式，遵循以下模式 成立于 unifi网络mcp:

模式 工具 上下文大小 描述
lazy 3 ~200个令牌 仅限元工具（默认，建议用于LLM）
eager 252 ~55K代币 所有工具直接注册

懒惰模式 （默认）只注册了3个提供252访问权限的元工具 UniFi操作（由控制器API生成）：

  • tool_index -按类别或资源搜索/筛选工具目录
  • execute -按名称和参数执行任何工具
  • batch -并行执行多个工具

这大大减少了上下文窗口的使用，同时保留了完整的 功能。LLM首先查询索引以查找相关工具，然后 通过调度器执行它们。

渴望模式 直接注册所有252个工具，这可能对非LLM有用 客户端或调试，但消耗大量上下文。

更新语义： 更新使用读-修改-写流程 控制器API。我们获取当前资源，合并您的字段，并提交 完整的对象。这避免了清除未指定的字段，但它不是原子性的 并发更新可能会竞争（最后一次写入获胜），因为UniFi API没有 暴露标签或修订ID。在实践中，这不太可能成为问题，但是 这是需要注意的事情。

ID解析

UniFi API的响应包含不透明的ID引用（例如。 network_id, usergroup_id, networkconf_id).默认情况下，服务器将这些解析为 通过查找引用的资源并注入 兄弟姐妹 _name 字段：

{
  "src_networkconf_id": "609fbf24e3ae433962e000de",
  "src_networkconf_name": "IOT"
}

Resolution使用按请求缓存，因此列出100条防火墙规则 参考网络只增加一个 ListNetwork API调用。典型的 开销为10-40ms，具体取决于有多少不同的资源类型 引用。

要禁用特定呼叫的解析，请传递 "resolve": false 在工具中 论据。

查询参数

所有列表操作都支持用于过滤的可选后处理参数 并预测结果。

过滤器 --按字段值匹配项目。支持三个操作员：

// Exact match
{"filter": {"type": "usw"}}

// Substring match (case-insensitive)
{"filter": {"name": {"contains": "office"}}}

// Regular expression (RE2 syntax: https://github.com/google/re2/wiki/Syntax)
{"filter": {"name": {"regex": "^ap-.*"}}}

// Multiple conditions (ANDed together)
{"filter": {"type": "uap", "name": {"contains": "echo"}}}

搜索 --对所有字符串字段值进行不区分大小写的全文搜索：

{ "search": "living room" }

领域 --预计响应仅包括特定密钥：

{ "fields": ["name", "ip", "mac"] }

参数可以组合。执行顺序已筛选→ 搜索→ 田地，所以你 可以过滤输出中排除的字段：

{
  "filter": { "type": "uap" },
  "search": "echo",
  "fields": ["name", "ip"]
}

发展

先决条件

开发中

# Clone the repository
git clone https://github.com/claytono/go-unifi-mcp.git
cd go-unifi-mcp

# Enter the development environment
nix develop
# Or with direnv:
direnv allow

# Install pre-commit hooks
pre-commit install

# Run linters
task lint

# Run tests
task test

# Run tests with coverage
task coverage

可用任务

task lint        # Run linters via pre-commit
task test        # Run tests
task coverage    # Run tests with coverage checks
task build       # Build the binary
task generate    # Run go generate

使用mcp-cli进行测试

开发环境包括 mcp-cli 用于交互式测试 MCP服务器。

  1. 创建 .envrc.local 使用您的UniFi凭据（未在git中跟踪）：

    export UNIFI_HOST="https://your-controller:443"
export UNIFI_API_KEY="your-api-key"
# Or use username/password:
# export UNIFI_USERNAME="admin"
# export UNIFI_PASSWORD="password"

  2. 构建二进制文件：

    task build

  3. 使用mcp-cli进行测试：

    这 .mcp_servers.json config提供了两个服务器条目：

    • go-unifi-mcp -渴望模式（252工具）
    • go-unifi-mcp-lazy -懒惰模式（3个元工具）

    渴望模式 （直接工具访问）：

    # List tools (shows all 252)
mcp-cli info go-unifi-mcp

# Call a tool directly
mcp-cli call go-unifi-mcp list_device '{}'
mcp-cli call go-unifi-mcp list_network '{"site": "default"}'

    懒惰模式 （元工具）：

    # List tools (shows only 3 meta-tools)
mcp-cli info go-unifi-mcp-lazy

# Query the tool index
mcp-cli call go-unifi-mcp-lazy tool_index '{}'
mcp-cli call go-unifi-mcp-lazy tool_index '{"category": "list"}'
mcp-cli call go-unifi-mcp-lazy tool_index '{"resource": "network"}'

# Execute a tool via the dispatcher
mcp-cli call go-unifi-mcp-lazy execute '{"tool": "list_device", "arguments": {}}'

# Batch execute multiple tools
mcp-cli call go-unifi-mcp-lazy batch '{"calls": [{"tool": "list_network", "arguments": {}}, {"tool": "list_device", "arguments": {}}]}'

鸣谢

本项目建立在以下基础之上：

  • 去unifi -UniFi Go客户端库 网络控制器
  • unifi网络mcp python 启发该项目的UniFi MCP服务器
  • mcp走 -Go SDK用于模型上下文 协议

许可证

MPL-2.0

相关 MCP