UISP API MCP服务器
一种用于与UISP（Ubiquiti互联网服务提供商）API交互的模型上下文协议（MCP）服务器。此服务器动态加载UISP swagger规范中的所有可用端点，并通过黑名单提供可配置的访问控制。
特性
- 动态工具生成：从swagger.json自动创建MCP工具
- 全面覆盖：显示所有UISP API端点（GET、POST、PUT、DELETE、PATCH）
- 可配置黑名单：控制哪些端点通过blacklist.yaml公开
- 基于方法的过滤：阻止整个HTTP方法（例如，所有POST/PUT/DELETE操作）
- 类型安全：保留API规范中的参数类型和枚举值
- 智能参数处理：正确处理路径和查询参数
- 自动检索：具有指数回退的内置重试逻辑
- 详细错误消息：来自API响应的丰富错误信息
安装
使用紫外线（推荐）
cd uisp_api_mcp
uv sync使用pip
cd uisp_api_mcp
pip install -e .配置
环境变量
创建一个 .env 项目根目录中的文件：
# Required
UISP_BASE_URL=https://your-uisp-instance.com
UISP_API_TOKEN=your-api-token
# Optional (with defaults)
UISP_API_TIMEOUT=30.0
UISP_API_RETRY_ATTEMPTS=3
UISP_API_RETRY_DELAY=1.0
UISP_DEFAULT_PAGE_SIZE=25
UISP_LOG_LEVEL=INFO黑名单配置
服务器使用 etc/blacklist.yaml 以控制暴露哪些端点。默认情况下，所有修改操作（POST、PUT、DELETE、PATCH）和敏感端点都被列入黑名单。
# Methods to exclude (blocks all endpoints using these HTTP methods)
methods:
- POST # Create operations
- PUT # Update operations
- DELETE # Delete operations
- PATCH # Partial update operations
# Tags to exclude (blocks all endpoints with these tags)
tags:
- Authorization
- Users
- Server
# ... etc
# Path patterns to exclude (regex patterns)
paths:
- .*login.*
- .*password.*
- .*auth.*
# ... etc在默认配置下，只公开GET（只读）操作。
获取UISP API令牌
- 登录您的UISP实例
- 导航到“设置”→ Users
- 选择您的用户帐户
- 生成API令牌
用法
克劳德桌面
添加到您的Claude Desktop配置中：
{
"mcpServers": {
"uisp": {
"command": "uv",
"args": ["--directory", "/path/to/uisp_api_mcp", "run", "uisp-api-mcp"],
"env": {
"UISP_BASE_URL": "https://your-uisp-instance.com",
"UISP_API_TOKEN": "your-api-token"
}
}
}
}命令行
# With UV
uv run uisp-api-mcp
# With Python
python -m uisp_api_mcp可用工具
服务器根据UISP swagger规范动态生成工具。使用默认黑名单（阻止所有POST、PUT、DELETE、PATCH方法），大约有120多种只读工具可用，包括：
通用工具
- 站点:
sites,sites_id,sites_search,sites_traffic - 设备:
devices,devices_id,devices_id_detail,devices_id_statistics - 监控:
logs,outages,nms_statistics,nms_summary - 网络:
datalinks,datalinks_id,devices_id_interfaces - 系统信息:
nms_info,nms_version,nms_enums
工具命名约定
工具的命名基于API端点路径和HTTP方法：
- 获取
/sites→sites - 获取
/sites/{id}→sites_id - 获取
/devices/{id}/detail→devices_id_detail - 发布
/sites→sites_post（如果没有列入黑名单） - 放
/sites/{id}→sites_id_put（如果没有列入黑名单） - 删除
/sites/{id}→sites_id_delete（如果没有列入黑名单）
参数类型
所有工具都保留原始API参数类型：
- 字符串枚举显示可用值（例如，“可用值：站点、端点、客户端”）
- 必需参数与可选参数已正确标记
- 路径参数（如
{id})自动处理
例子
列出所有网站
Tool: sites
Parameters:
- type_: "site" # Available values: site, endpoint, client, subscriber
- ucrm: true # Only sites bound with CRM获取特定网站详细信息
Tool: sites_id
Parameters:
- id_: "9ef86767-fd8d-487c-8c97-77f763c5a99a"
- ucrmDetails: true列出设备
Tool: devices
Parameters:
- siteId: "site-uuid"
- type_: ["erouter", "eswitch"] # Device types
- role: ["router", "switch"] # Device roles获取设备统计信息
Tool: devices_id_statistics
Parameters:
- id_: "device-uuid"
- interval: "hour"
- start: "2024-01-01T00:00:00Z"
- period: "86400000" # 24 hours in milliseconds错误处理
服务器包括全面的错误处理：
- 身份验证错误（401）
- 未发现错误（404）
- 验证错误（400）
- 速率限制（429）
- 连接超时
- 指数回退自动重试
发展
项目结构
uisp_api_mcp/
├── pyproject.toml
├── README.md
├── .env
├── etc/
│ ├── swagger.json # UISP API specification
│ └── blacklist.yaml # Endpoint blacklist configuration
└── src/
└── uisp_api_mcp/
├── __init__.py
├── __main__.py
├── client.py # HTTP client with retry logic
├── exceptions.py # Custom exception types
├── server.py # Dynamic MCP server
├── settings.py # Configuration management
└── swagger_tools.py # Swagger parsing and tool generation运作原理
- Swagger加载：服务器读取
etc/swagger.json启动时 - 黑名单过滤：端点根据以下内容进行筛选
etc/blacklist.yaml（方法、标签、路径） - 工具生成：每个允许的端点都成为具有适当类型的MCP工具
- 参数处理：替换路径参数，传递查询参数
- 错误处理：捕捉API错误，并通过详细信息进行丰富
添加/删除端点
要修改公开的端点，请执行以下操作：
- 编辑
etc/blacklist.yaml - 添加或删除：
- HTTP方法（例如，从方法列表中删除POST以允许POST操作） - 标签（阻止/允许所有具有特定标签的端点） - 路径模式（用于匹配特定端点的正则表达式模式）
- 重新启动服务器
更新API规范
要使用更新的UISP API版本进行更新，请执行以下操作：
- 替换
etc/swagger.json使用最新版本 - 服务器将自动接收新的端点
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
支持
有关UISP API文件，请访问：https://help.ui.com/hc/en-us/articles/115002943188-UISP-API
有关此MCP服务器的问题，请在GitHub上打开问题。