Aruba Central MCP

aruba-central-mcp

English | 日本語

适用于 Aruba Central（GreenLake New Central API）的 MCP 服务。

通过 STDIO 传输协议，向兼容 MCP 的 AI 助手（Claude Code、Claude Desktop、OpenAI Codex 等）提供接入点、交换机和无线客户端的状态信息。

文档：https://shigechika.github.io/aruba-central-mcp/

功能

接入点

工具	说明
list_aps	列出所有接入点（可选按站点／状态筛选）
list_radios	列出 AP 无线电信息（信道、利用率、噪声底限、发射功率）
list_bssids	列出所有 BSSID
list_wlans	列出 WLAN（SSID、安全性、VLAN）
list_swarms	列出 AP 群组／集群
get_ap_status	获取指定 AP 的详细状态
get_ap_throughput	获取 AP 吞吐量趋势（随时间变化的发送／接收数据量）
get_top_aps	按带宽使用量列出排名靠前的 AP（无线／有线／总计）

客户端

工具	说明
list_clients	列出已连接的无线客户端（可选按 SSID／频段筛选）
find_client_by_mac	按 MAC 地址查找客户端（直接调用 API 查询）
get_clients_trend	客户端数量趋势
get_top_clients_by_usage	按带宽使用量列出排名靠前的客户端
get_client_mobility_trail	客户端漫游历史

基础设施

工具	说明
list_switches	列出所有交换机
get_site_summary	汇总站点级别的信息（AP 数量、客户端数量）
health_check	报告服务版本并验证 Aruba Central 身份验证（不获取数据）
daily_brief	一次性晨间 AP 健康检查：列出离线 AP 比例超过阈值的站点

固件

工具	说明
firmware_status	按群组列出群组、站点、当前运行版本、推荐版本和升级状态；可按群组、站点和／或群组筛选。配置 Classic Central 后，还会列出 Classic 群组、群组的合规版本（Central 下一步将群组升级到的版本）及其计划时间、Classic 的升级状态和原因，以及仅存在于 Classic 中的（过时）群组
firmware_versions	Classic Central 为指定设备类型或单个群组提供的固件版本（仅在配置 Classic Central 后注册）

所有工具均为只读；不会进行配置或升级。请参阅 docs/firmware-api-notes.md，了解各 API 报告的内容。

亮点

• 服务端 OData 筛选，高效查询
• OAuth2 客户端凭据身份验证（GreenLake SSO）
• 自动分页，处理大型结果集
• 令牌自动刷新，在过期前完成刷新
• 轻量级：仅依赖 mcp SDK 和 httpx（不使用 pandas）

前提条件

• Python 3.10+
• 可访问 API 的 Aruba Central 账户（GreenLake New Central API）
• OAuth2 客户端凭据（客户端 ID 和密钥）

安装

# uv
uv pip install aruba-central-mcp

# pip
pip install aruba-central-mcp

也可以不安装直接运行：

uvx aruba-central-mcp

从源代码安装：

git clone https://github.com/shigechika/aruba-central-mcp.git
cd aruba-central-mcp

# uv
uv sync

# pip
pip install -e .

配置

设置以下环境变量：

变量	说明	示例
ARUBA_CENTRAL_BASE_URL	API 网关 URL	apigw-uswest4.central.arubanetworks.com
ARUBA_CENTRAL_CLIENT_ID	OAuth2 客户端 ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ARUBA_CENTRAL_CLIENT_SECRET	OAuth2 客户端密钥	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

可选：Classic Central（固件详情）

Classic Central 组中的 AOS-8 Instant AP 由 Classic Central 升级， 只有其 API 会报告集群升级失败的原因、组的合规版本以及可用版本。设置以下全部四项以启用：

变量	描述
ARUBA_CLASSIC_BASE_URL	Classic API 网关主机，apigw-<region>.central.arubanetworks.com
ARUBA_CLASSIC_CLIENT_ID	API 网关应用的客户端 ID
ARUBA_CLASSIC_CLIENT_SECRET	该应用的客户端密钥
ARUBA_CLASSIC_TOKEN_FILE	保存令牌对的 JSON 文件；此服务每次刷新时都会重写该文件

使用 Classic Central 的 API Gateway 为该应用签发的访问令牌和刷新令牌初始化令牌文件一次，并确保只有运行此服务的用户可以读取：

umask 077
printf '{"access_token": "%s", "refresh_token": "%s"}\n' "$ACCESS" "$REFRESH" > /path/to/classic-token.json

每次刷新时都会替换刷新令牌（旧令牌随即失效），因此只允许此服务刷新令牌，并让运行此服务的每个进程都指向同一个文件：刷新操作会通过文件旁的锁文件串行执行。刷新令牌遭拒时，health_check 会报告 classic: error 并要求提供新的令牌对；如果只设置了部分 ARUBA_CLASSIC_* 变量，则会报告 classic: misconfigured 并指出缺少哪些变量。文件所在目录必须对该用户可写（新的令牌对会先写入旁边的文件，再进行重命名）；否则，服务会拒绝刷新，以免丢失轮换后的令牌。Windows 上没有跨进程锁，因此请只运行一个进程。

如何获取 API 凭据

1. 登录 HPE GreenLake Platform
2. 前往 Manage Workspace > Personal API clients
3. 点击 Create Personal API client
4. 输入昵称，并选择 Aruba Central 作为服务
5. 复制 client_id 和 client_secret — 密钥只会显示一次

详情请参阅：

• OAuth APIs for Access Token
• Making API Calls

使用方法

Claude Code（插件）

此仓库同时也是一个单插件市场，因此 Claude Code 可以为你安装此服务：

/plugin marketplace add shigechika/aruba-central-mcp
/plugin install aruba-central-mcp@aruba-central-mcp

该插件会启动 uvx aruba-central-mcp，并读取配置中所述的相同三个环境变量；请在启动 Claude Code 前导出这些变量。它还会传递四个可选的 ARUBA_CLASSIC_* 变量，因此导出这些变量后，firmware_status 会获取 Classic 详情，并会提供 firmware_versions；如果未设置，这些变量会以空值传入，Classic 功能则保持关闭。

运行 Claude Code 的进程必须能在 PATH 中找到 uvx — 登录 shell 通常已包含它，但通过 GUI 启动的应用可能没有；如果插件无法启动，请在系统范围内安装 uv。

Claude Code（手动）

claude mcp add aruba-central \
  -e ARUBA_CENTRAL_BASE_URL=apigw-uswest4.central.arubanetworks.com \
  -e ARUBA_CENTRAL_CLIENT_ID=your-client-id \
  -e ARUBA_CENTRAL_CLIENT_SECRET=your-client-secret \
  -- uvx aruba-central-mcp

或者添加到 .mcp.json：

{
  "mcpServers": {
    "aruba-central": {
      "command": "uvx",
      "args": ["aruba-central-mcp"],
      "env": {
        "ARUBA_CENTRAL_BASE_URL": "apigw-uswest4.central.arubanetworks.com",
        "ARUBA_CENTRAL_CLIENT_ID": "your-client-id",
        "ARUBA_CENTRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "aruba-central": {
      "command": "uvx",
      "args": ["aruba-central-mcp"],
      "env": {
        "ARUBA_CENTRAL_BASE_URL": "apigw-uswest4.central.arubanetworks.com",
        "ARUBA_CENTRAL_CLIENT_ID": "your-client-id",
        "ARUBA_CENTRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Codex

codex mcp add aruba-central \
  --env ARUBA_CENTRAL_BASE_URL=apigw-uswest4.central.arubanetworks.com \
  --env ARUBA_CENTRAL_CLIENT_ID=your-client-id \
  --env ARUBA_CENTRAL_CLIENT_SECRET=your-client-secret \
  -- uvx aruba-central-mcp

其他任何可启动 stdio 服务的 MCP 客户端也采用相同方式：将 uvx aruba-central-mcp 设为命令，并在其环境中设置三个 ARUBA_CENTRAL_* 变量。

直接执行

export ARUBA_CENTRAL_BASE_URL="apigw-uswest4.central.arubanetworks.com"
export ARUBA_CENTRAL_CLIENT_ID="your-client-id"
export ARUBA_CENTRAL_CLIENT_SECRET="your-client-secret"
python3 -m aruba_central_mcp

CLI 选项

aruba-central-mcp --version   # Print version and exit
aruba-central-mcp --help      # Show usage and required environment variables
aruba-central-mcp --check     # Verify environment variables and OAuth2 authentication, then exit
aruba-central-mcp             # Start MCP server (STDIO, default)

不带任何选项时，进程会作为 MCP STDIO 服务运行（MCP 客户端使用的模式）。

--check 退出代码：0 表示成功，1 表示配置错误，2 表示身份验证错误。

开发

git clone https://github.com/shigechika/aruba-central-mcp.git
cd aruba-central-mcp

# uv
uv sync --dev
uv run pytest -v

# pip
python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest -v

实时冒烟测试

单元测试套件在传输层模拟 Central，因此速度很快——但也因此无法发现某个工具是否已停止返回真实数据。scripts/smoke_test.py 会使用已配置的租户测试每个已注册工具，并在回答为空、格式错误或出错时失败：

# needs the same ARUBA_CENTRAL_* environment variables as the server
uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only radios --traceback

• 只读。 这里的每个工具都只读取数据；Central 中没有配置任何内容。未来新增的写入工具必须标记为会更改状态并跳过，且有测试强制执行这一点。
• 报告中不包含任何负载。 仅包含工具名称、状态和行数；错误文本也会经过脱敏，因为错误通常会引用其查询的设备、客户端 MAC 地址或站点。
• 规格中不包含任何网络特定信息。 每设备工具所需的 AP、序列号和客户端 MAC 地址会在运行时从列表中发现；如果网络中没有可用对象，则跳过。两项测试确保这一点：一项禁止将这些参数写成字面值，另一项禁止文件中任何位置出现类似地址的内容，因为此代码库是公开的。
• 对于列表和时间序列工具，空回答也算通过——没有配置任何 AP 群集的站点确实存在于实际部署中——但如果查询使用的是几秒前才发现的名称，则结果不应为空；这些探测会检查这一点。
• CI 会强制执行成本较低的部分：注册工具时若没有对应的探测规格，构建就会失败（tests/test_smoke_probes.py），因此添加工具时必须回答“我们如何知道它能正常工作？”。
• scripts/smoke_harness.py 是执行引擎，不包含任何 Central 相关知识：它在共用该引擎的服务之间保持一致，因此修复引擎错误时只需修复一次，然后同步该文件，而不是只修改此副本。

首次运行就发现了一个实际问题：get_client_mobility_trail 请求的页面大小被端点拒绝，因此该工具对所有客户端都一直失败。

API 参考

此服务使用 GreenLake New Central API：

• /network-monitoring/v1/aps — 接入点
• /network-monitoring/v1/radios — AP 射频
• /network-monitoring/v1/bssids — BSSID
• /network-monitoring/v1/wlans — WLAN
• /network-monitoring/v1/swarms — AP 群集／集群
• /network-monitoring/v1/switches — 交换机
• /network-monitoring/v1/clients — 客户端
• /network-monitoring/v1/clients-trend — 客户端数量趋势
• /network-monitoring/v1/clients-topn-usage — 使用量最高的客户端
• /network-monitoring/v1/top-aps-by-usage — 使用量最高的 AP

许可证

MIT