uisp API MCP

MCP运维云端

提供方 sevaepsteyn

运维云端 stdio · 本地进程 Token 社区 / 第三方 Claude DesktopClaude
查看接入方式

一个用于与UISP API交互的模型上下文协议服务器,提供动态端点加载和可配置的访问控制。

一句话选型结论

按资料字段整理

uisp API MCP 属于运维云端类 MCP 服务器,stdio · 本地进程,Token,可直接接入 Claude Desktop、Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 18 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量18暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

API网关Python本地部署访问控制动态端点网络管理服务提供商

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
pip install -e .

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 18 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 18 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
uisp API MCP当前 18 stdio · 本地进程 本地部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方sevaepsteyn上游标注的维护方 sevaepsteyn
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

6.3 KB
来自项目仓库与上游目录的原文,未做删改

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响应的丰富错误信息

安装

使用紫外线(推荐)```bash

cd uisp_api_mcp
uv sync


### 使用pip```bash
cd uisp_api_mcp
pip install -e .

配置

环境变量

创建一个 .env 项目根目录中的文件:```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)和敏感端点都被列入黑名单。```yaml
# 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令牌

  1. 登录您的UISP实例
  2. 导航到“设置”→ Users
  3. 选择您的用户帐户
  4. 生成API令牌

用法

克劳德桌面

添加到您的Claude Desktop配置中:```json
{
"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"
}
}
}
}


### 命令行```bash
# 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
```

运作原理

  1. Swagger加载:服务器读取 etc/swagger.json 启动时
  2. 黑名单过滤:端点根据以下内容进行筛选 etc/blacklist.yaml (方法、标签、路径)
  3. 工具生成:每个允许的端点都成为具有适当类型的MCP工具
  4. 参数处理:替换路径参数,传递查询参数
  5. 错误处理:捕捉API错误,并通过详细信息进行丰富

添加/删除端点

要修改公开的端点,请执行以下操作:

  1. 编辑 etc/blacklist.yaml
  2. 添加或删除:
    - HTTP方法(例如,从方法列表中删除POST以允许POST操作)
    - 标签(阻止/允许所有具有特定标签的端点)
    - 路径模式(用于匹配特定端点的正则表达式模式)
  3. 重新启动服务器

更新API规范

要使用更新的UISP API版本进行更新,请执行以下操作:

  1. 替换 etc/swagger.json 使用最新版本
  2. 服务器将自动接收新的端点

许可证

MIT许可证-有关详细信息,请参阅许可证文件。

支持

有关UISP API文件,请访问:https://help.ui.com/hc/en-us/articles/115002943188-UISP-API

有关此MCP服务器的问题,请在GitHub上打开问题。

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
uisp API MCP 怎么安装?

在客户端按下面的安装命令接入:pip install -e .。装完在客户端配置里引用同一个包或端点。

uisp API MCP 怎么在 Claude Desktop、Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

uisp API MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

uisp API MCP 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

uisp API MCP 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

uisp API MCP 能提供哪些能力?

资料显示约 18 个工具;能力标签包括 API网关、Python、Claude、访问控制。具体工具清单以官方文档为准。

uisp API MCP 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

uisp API MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。