使用说明
UniFi MCP服务器
A. 模型上下文协议 用于通过Claude Desktop或其他MCP客户端管理UniFi网络的服务器。
特性
- 18个MCP工具 -全面的网络管理能力
- OAuth 2.1+PKCE -使用Cloudflare Access进行安全身份验证
- API密钥验证 -使用官方UniFi API和X-API-KEY
- 符合MCP 2025-11-25标准 -完全符合规范
- 远程就绪 -专为通过Cloudflare隧道访问而设计
快速开始
1.生成UniFi API密钥
在您的UniFi控制器/UDM中：
- 首选 设置→ 控制平面→ 集成
- 点击 生成API密钥
- 复制密钥
2.配置环境
cp .env.example .env
编辑 .env:
# Server
BASE_URL=https://your-domain.com
# Cloudflare Access for SaaS (OAuth identity provider)
CF_ACCESS_TEAM=your-team-name
CF_CLIENT_ID=your-client-id
CF_CLIENT_SECRET=your-client-secret
# UniFi Controller
UNIFI_HOST=192.168.1.1
UNIFI_API_KEY=your-api-key-from-step-1
3.从Docker开始
docker compose up -d
4.配置Cloudflare
- 创建 Cloudflare 隧道 指向您的服务器
- 创建一个 SaaS访问 Zero Trust中的应用程序：
- 协议：OIDC
- 重定向URL:
https://your-domain.com/callback
- 使用您的隧道URL与Claude Desktop连接
可用工具
客户管理
| 工具 | 说明 |
|---|---|
list_clients |
列出所有连接的设备 |
get_client |
通过MAC获取特定客户端的详细信息 |
search_devices |
按名称、IP或MAC搜索 |
block_client |
阻止网络中的设备 |
unblock_client |
解锁设备 |
reconnect_client |
强制客户端重新连接 |
list_blocked_clients |
列出被阻止的设备 |
设备管理
| 工具 | 说明 |
|---|---|
list_devices |
列出所有UniFi设备（AP、交换机、网关） |
list_access_points |
列出具有状态的接入点 |
restart_device |
重新启动AP或交换机 |
网络配置
| 工具 | 说明 |
|---|---|
list_networks |
列出VLAN和子网 |
list_wlans |
列出无线SSID |
list_port_forwards |
列出端口转发规则 |
监控
| 工具 | 说明 |
|---|---|
get_network_health |
网络健康统计 |
list_events |
最近的网络事件 |
list_alarms |
当前和最近的警报 |
建筑
Claude Desktop
↓
Cloudflare Tunnel (secure tunnel)
↓
UniFi MCP Server (OAuth 2.1 + MCP)
↓
UniFi Controller/UDM (X-API-KEY)
身份验证流程
此服务器使用Cloudflare Access作为身份提供者实现OAuth 2.1：
- MCP客户端通过以下方式发现OAuth端点
/.well-known/oauth-authorization-server - 客户端启动OAuth流
/authorize使用PKCE - 用户通过Cloudflare Access进行身份验证（支持Entra ID、Google等）
- 经批准后，客户在以下地址交换代币代码
/token - 客户端访问
/mcp带有Bearer代币
OAuth端点
| 端点 | 描述 |
|---|---|
/.well-known/oauth-authorization-server |
授权服务器元数据 |
/.well-known/oauth-protected-resource/mcp |
受保护的资源元数据（RFC 9728） |
/authorize |
授权端点（自动注册客户端） |
/token |
令牌端点 |
/register |
动态客户端注册 |
/callback |
Cloudflare OAuth回调 |
配置
| 变量 | 必填 | 描述 |
|---|---|---|
PORT |
无 | 服务器端口（默认值：3000） |
BASE_URL |
是 | OAuth重定向的公共URL |
CF_ACCESS_TEAM |
是 | Cloudflare Access团队名称 |
CF_CLIENT_ID |
是 | 来自SaaS应用程序的Access |
CF_CLIENT_SECRET |
是 | 来自SaaS应用程序的Access |
UNIFI_HOST |
是 | UniFi控制器IP |
UNIFI_PORT |
否 | 控制器端口（默认值：443） |
UNIFI_API_KEY |
是 | 来自UniFi的API密钥 |
UNIFI_SITE |
否 | 站点名称（默认：“默认”） |
安全
- OAuth 2.1+PKCE -安全令牌交换
- Cloudflare 隧道 -无直接IP暴露
- Cloudflare访问 -边缘身份验证
- API密钥认证 -未存储密码，范围访问
推荐的WAF规则
考虑阻塞非必要路径：
- 允许：
/.well-known/*,/register,/authorize,/callback,/token,/mcp - 阻止或保护：
/,/health
技术栈
- 带ES模块的Node.js 22
- @模型上下文协议/sdk
- Express.js
- Docker与Alpine Linux
发展
# Install dependencies
npm install
# Run with hot-reload
npm run dev
# Check syntax
node --check server.js
许可证
麻省理工学院
