go-unifi-mcp

关键词

UniFi上下文提供工具执行数据接口云端对话

使用说明内容（Markdown格式）

go-unifi-mcp 使用指南

  • 项目简介

    • 这是一个基于 Model Context Protocol 的 UniFi MCP 服务器实现。它把 UniFi Network Controller 的资源、可执行工具以及提示模板以标准化的 MCP 服务形式暴露给 LLM 客户端（例如 Claude、mcp-cli 等），通过 JSON-RPC 与客户端通信，方便 AI 系统获取上下文信息、执行外部操作、以及渲染对话模板。

  • 主要功能点

    • 资源托管与访问：把 UniFi 的网络、设备、用户等资源暴露为 MCP 资源，提供统一的数据访问能力。
    • 工具注册与执行：根据 UniFi 的字段定义生成工具元数据，注册并执行工具，支持直接访问和分派执行（延迟加载模式与直接加载模式）。
    • 提示模板与渲染：提供可定制的 Prompt 模板和渲染能力，便于 LLM 与 UniFi 的上下文交互。
    • JSON-RPC 通信：服务器端遵循 MCP 的请求/响应模型，通过标准的 JSON-RPC 进行交互。
    • 会话与能力声明：服务器端实现会话管理及能力声明，支持不同传输协议（如标准输出、SSE、WebSocket 等）以适配多种前端。
    • 配置驱动：通过 UniFi 控制器的 API Key 或用户名/密码进行认证，灵活配置站点、SSL 校验、日志级别等。

  • 安装步骤

    • 获取代码并编译
      • 拷贝仓库源码到本地，进入项目目录后执行 go build ./...
    • 运行前置条件
      • 需要一个 UniFi Network Controller 实例，且具备 API Key 或用户名/密码的认证信息。
    • 运行方式
      • 通过环境变量配置 UniFi 控制器信息，启动 MCP 服务器二进制程序即可。
    • 环境变量（常用）
      • UNIFI_HOST：UniFi 控制器地址（必填）
      • UNIFI_API_KEY：API Key（优选认证方法）
      • UNIFI_USERNAME：用户名（若使用密码认证时必填）
      • UNIFI_PASSWORD：密码（若使用密码认证时必填）
      • UNIFI_SITE：站点名，默认 default
      • UNIFI_VERIFY_SSL：是否校验 SSL 证书，默认 true
      • UNIFI_LOG_LEVEL：日志等级，disabled|trace|debug|info|warn|error，默认 error
      • UNIFI_TOOL_MODE：工具注册模式，lazy（默认，只有元工具）、eager（直接注册全部工具）
    • Claude/客户端配置（示例，用于在 Claude Desktop 或类似工具中接入 MCP 服务器）
      • 使用二进制方式运行时，请在客户端配置中指定服务器的命令和环境变量，例如：
        • command: /usr/local/bin/go-unifi-mcp
        • env: UNIFI_HOST: https://your-controller:443 UNIFI_API_KEY: your-api-key
    • 额外说明
      • 仓库包含了工具元数据的自动生成、以及多种测试覆盖，用于确保工具与 UniFi API 的字段对齐。若要在你的环境中使用，请确保 UniFi Controller 版本与 go-unifi 库版本兼容。

  • 服务器配置（给 MCP 客户端的 json 配置示例） { "mcpServers": { "unifi": { "command": "/usr/local/bin/go-unifi-mcp", "args": [], "env": { "UNIFI_HOST": "https://your-controller:443", "UNIFI_API_KEY": "your-api-key", "UNIFI_SITE": "default", "UNIFI_VERIFY_SSL": "true", "UNIFI_LOG_LEVEL": "error", "UNIFI_TOOL_MODE": "lazy" } // 说明： // - command: 启动 MCP 服务器的可执行路径 // - args: 启动参数（当前实现通常不依赖额外参数，可留空） // - env: 运行时所需的环境变量，包含 UniFi 控制器信息、站点、以及日志和模式设置 } } }

  • 基本使用方法

    • 启动服务器后，LLM 客户端可通过 MCP 的标准接口向 UniFi 资源发起查询，或通过工具执行来操作 UniFi 资源。
    • 通过 mcp-cli 等工具，可以对已注册的工具进行信息查看、调用和批量执行，验证工具的输出是否包含所需的资源信息。
    • 若需要对返回结果进行名称解析（如把网络_id 转换为网络名称），需要在客户端请求中允许解析，或在服务器配置中通过解析中间件启用解析。
    • 如要排查问题，请检查环境变量、UniFi 控制器的可访问性，以及工具模式设置（lazy/eager）的影响。

服务器信息

访问项目