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.

1. 用户名/密码：使用本地管理员帐户。集 UNIFI_HOST,

UNIFI_USERNAME，以及 UNIFI_PASSWORD.

克劳德桌面版

添加到您的 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 mcp add unifi -- go-unifi-mcp

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

环境变量

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

日志级别

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

工具模式

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

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

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

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

渴望模式 直接注册所有242个工具，这可能对非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"]
}

发展

先决条件

• 尼克斯 启用薄片
• direnv （可选但推荐）

开发中

# 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"

1. 构建二进制文件：

   task build

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

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

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

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

   # List tools (shows all 242)
   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