aruba-central-mcp
English | 日本語
MCP server for Aruba Central (GreenLake New Central API).
Exposes access point, switch, and wireless client status to MCP-compatible AI assistants (Claude Code, Claude Desktop, OpenAI Codex, etc.) via STDIO transport.
Documentation: https://shigechika.github.io/aruba-central-mcp/
Features
Access Points
Clients
Infrastructure
Firmware
Every tool reads; nothing is configured or upgraded. See docs/firmware-api-notes.md for which API reports what.
Highlights
- Server-side OData filtering for efficient queries
- OAuth2 Client Credentials authentication (GreenLake SSO)
- Automatic pagination for large result sets
- Token auto-refresh before expiration
- Lightweight: only
mcp SDK + httpx (no pandas)
Prerequisites
- Python 3.10+
- Aruba Central account with API access (GreenLake New Central API)
- OAuth2 client credentials (client ID and secret)
Setup
Or run without installing:
From source:
Configuration
Set the following environment variables:
Optional: Classic Central (firmware details)
AOS-8 Instant APs in Classic Central groups are upgraded from Classic Central,
and only its API reports why a swarm's upgrade failed, the group compliance
version and the versions on offer. Set all four to enable that:
Bootstrap the token file once with the access and refresh token Classic
Central's API Gateway issues for that application, readable only by the user
the server runs as:
The refresh token is replaced on every refresh (the old one stops working), so
let only this server refresh it, and point every process that runs it at the
same file: refreshes are serialised with a lock file next to it. When the
refresh token is rejected, health_check reports classic: error and asks for
a new pair; when only some ARUBA_CLASSIC_* variables are set it reports
classic: misconfigured and names the missing ones. The directory holding the
file must be writable by that user (the new pair is written next to it, then
renamed); without that, the server refuses to refresh rather than lose the
rotated token. Windows has no cross-process lock here, so run one process there.
How to obtain API credentials
- Log in to HPE GreenLake Platform
- Go to Manage Workspace > Personal API clients
- Click Create Personal API client
- Enter a nickname and select Aruba Central as the service
- Copy the
client_id and client_secret — the secret is shown only once
For details, see:
Usage
Claude Code (plugin)
This repository doubles as a single-plugin marketplace, so Claude Code can install
the server for you:
The plugin launches uvx aruba-central-mcp and reads the same three environment
variables described in Configuration; export them before
starting Claude Code. It also passes the four optional ARUBA_CLASSIC_*
variables through, so firmware_status gets its Classic details and
firmware_versions is offered when they are exported; left unset they arrive
empty and Classic stays off.
uvx must be on the PATH of the process that runs Claude Code — a login
shell usually has it, but a GUI-launched app may not; install
uv system-wide if the plugin fails to start.
Claude Code (manual)
Or add to .mcp.json:
Claude Desktop
Add to claude_desktop_config.json:
Codex
Any other MCP client that launches stdio servers works the same way: give it
uvx aruba-central-mcp as the command and set the three ARUBA_CENTRAL_*
variables in its environment.
Direct execution
CLI Options
With no options, the process runs as an MCP STDIO server (the mode used by MCP clients).
--check exit codes: 0 success, 1 config error, 2 auth error.
Development
Live smoke test
The unit suite mocks Central at the transport layer, which is what makes it
fast — and also what makes it blind to a tool that has stopped returning real
data. scripts/smoke_test.py runs every registered tool against the
configured tenant and fails on empty, malformed or error answers:
- Read-only. Every tool here reads; nothing in Central is configured. A
future tool that writes must be listed as state-changing and skipped, and a
test enforces that.
- No payloads in the report. Tool names, statuses and row counts only;
error text is redacted too, since an error routinely quotes the device,
client MAC or site it was asked about.
- Nothing network-specific in the specs. The AP, the serial number and the
client MAC that the per-device tools need are discovered at run time from the
listings, and skipped when the network has none to offer. Two tests keep it
that way: one refuses those parameters as literals, the other bans anything
address-shaped anywhere in the file, because this repository is public.
- Empty answers pass for the listings and the time-series tools — a site with
no swarms configured is a real deployment — but a lookup handed a name
discovered seconds earlier must not come back empty, and those probes say so.
- CI enforces the cheap half: a tool registered without a probe spec fails the
build (
tests/test_smoke_probes.py), so adding a tool forces the question
"how would we know it works?".
scripts/smoke_harness.py is the engine and holds no Central knowledge: it
is kept identical across the servers that share it, so fix engine bugs once
and sync the file rather than patching this copy.
Its first run found a real one: get_client_mobility_trail was requesting a
page size the endpoint rejects, so the tool had been failing for every client.
API Reference
This server uses the GreenLake New Central API:
/network-monitoring/v1/aps — Access points/network-monitoring/v1/radios — AP radios/network-monitoring/v1/bssids — BSSIDs/network-monitoring/v1/wlans — WLANs/network-monitoring/v1/swarms — AP swarms/clusters/network-monitoring/v1/switches — Switches/network-monitoring/v1/clients — Clients/network-monitoring/v1/clients-trend — Client count trends/network-monitoring/v1/clients-topn-usage — Top clients by usage/network-monitoring/v1/top-aps-by-usage — Top APs by usage
License
MIT
