# central-mcp-server

![PyPI - Python Version](https://img.shields.io/pypi/pyversions/central-mcp-server)
![PyPI - License](https://img.shields.io/pypi/l/central-mcp-server)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

Community MCP server for HPE Aruba Networking Central. This exposes your Central data as tools that AI assistants can query directly.

---

> [!WARNING]
> **Unofficial Community Project**
>
> This is **not** an officially supported product of HPE. It is provided as-is, with no warranty or guarantee of fitness for any purpose.
>
> - Review your organization's **corporate device and data policies** before connecting this server to any AI assistant.
> - **Never share credentials** (API secrets, API keys) with AI model providers unless your security policy explicitly permits it.
> - All read operations query live data from your HPE Aruba Networking Central instance. Recommended to test MCP server use in non-production or lab environments where possible before running on production.

---

## Table of Contents

- [Overview](#overview)
- [Getting Started](#getting-started)
  - [Getting Your Credentials](#getting-your-credentials)
  - [Installation](#installation)
  - [MCP Client Configuration](#mcp-client-configuration)
    - [Claude Desktop](#claude-desktop)
    - [Claude Code](#claude-code)
    - [GitHub Copilot (VS Code)](#github-copilot-vs-code)
    - [HTTP Transport (Streamable HTTP)](#http-transport-streamable-http)
- [Supported Capabilities](#supported-capabilities)
- [What You Can Ask](#what-you-can-ask)
- [Example Queries](#example-queries)
- [Dev Setup](#dev-setup)

---

## Overview

`central-mcp-server` wraps Central REST APIs and exposes them as [MCP (Model Context Protocol)](https://modelcontextprotocol.io) tools — **12 MCP tools** across inventory, monitoring, events, alerts, and troubleshooting. Once configured, AI assistants like Claude or GitHub Copilot can answer questions like:

- *"Which sites have poor health scores right now?"*
- *"Show me all failed wireless clients at HQ in the last 24 hours."*
- *"Show me all online access points at the Chicago office."*
- *"What events happened on switch SW-CORE-01 yesterday?"*

![Architecture](architecture.svg)

See the [full overview guide](https://developer.arubanetworks.com/new-central/docs/central-mcp-overview) for a deeper look at capabilities, limitations, and how the server works.

---

## Getting Started

### Getting Your Credentials

You need three values to connect this server to Central's REST APIs: `CENTRAL_BASE_URL`, `CENTRAL_CLIENT_ID`, and `CENTRAL_CLIENT_SECRET`.

#### API Gateway Base URL (CENTRAL_BASE_URL)

The API gateway base URL for your Central account (e.g. `https://us5.api.central.arubanetworks.com`).

> For instructions on how to locate your base URL, see [Finding Your Base URL in Central](https://developer.arubanetworks.com/new-central/docs/getting-started-with-rest-apis#finding-your-base-url).

#### API Client Credentials (CENTRAL_CLIENT_ID & CENTRAL_CLIENT_SECRET)

OAuth credentials created through the HPE GreenLake Platform:

1. Log in to your HPE GreenLake account and open **Manage Workspace**.
2. Click **Personal API clients**.
3. Click **Create Personal API client**.
4. Give it a nickname (e.g. `central-mcp-server`) and select your **HPE Aruba Networking Central** instance from the service dropdown.
5. Click **Create personal API client**.
6. Copy both the **Client ID** and **Client Secret** immediately. The platform does not store the secret and it cannot be retrieved later.

> Full guide: [Generating and Managing Access Tokens](https://developer.arubanetworks.com/new-central/docs/generating-and-managing-access-tokens)

---

### Installation

Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) if you haven't already. It's the only prerequisite.

**Using an MCP client (Claude Desktop, Claude Code, GitHub Copilot)?**
No install command needed. Jump to [MCP Client Configuration](#mcp-client-configuration), the client fetches and runs the server automatically via `uvx`.

**Want the server as a persistent CLI tool on your PATH?**

```bash
uv tool install --prerelease=allow central-mcp-server
```

> `--prerelease=allow` is required because this server depends on `pycentral`, which currently only has a pre-release version on PyPI. uv skips pre-releases by default.

See the [full setup guide](https://developer.arubanetworks.com/new-central/docs/central-mcp-setup) for prerequisites, troubleshooting, and step-by-step instructions.

---

### MCP Client Configuration

Replace the placeholder values with your actual credentials in all examples below.

#### Optional: Code Mode Transform (`DYNAMIC_TOOLS`)

`DYNAMIC_TOOLS` is optional and only affects startup behavior:

- Code Mode is enabled only when `DYNAMIC_TOOLS` is set to `true` (case-insensitive).
- Code Mode is disabled when `DYNAMIC_TOOLS` is not set or set to any other value.
- Variable name is strict: use `DYNAMIC_TOOLS` (plural). `DYNAMIC_TOOL` is ignored.

When enabled, the server starts with `CodeMode()` and exposes Code Mode meta-tools to the client. When disabled, the server runs without the transform and exposes the normal registered tool catalog directly. Recommended to use `CodeMode()` when you have multiple MCP servers running to preserve your context window.

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "central-mcp": {
      "command": "uvx",
      "args": ["--prerelease=allow", "central-mcp-server"],
      "env": {
        "CENTRAL_BASE_URL": "your-central-base-url",
        "CENTRAL_CLIENT_ID": "your-client-id",
        "CENTRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

See the [Claude Desktop setup guide](https://developer.arubanetworks.com/new-central/docs/central-mcp-claude-desktop-setup) for full steps and troubleshooting.

#### Claude Code

```bash
claude mcp add central-mcp \
  -e CENTRAL_BASE_URL=your-central-base-url \
  -e CENTRAL_CLIENT_ID=your-client-id \
  -e CENTRAL_CLIENT_SECRET=your-client-secret \
  -- uvx --prerelease=allow central-mcp-server
```

See the [Claude Code setup guide](https://developer.arubanetworks.com/new-central/docs/central-mcp-claude-code-setup) for full steps and troubleshooting.

#### GitHub Copilot (VS Code)

Add `.vscode/mcp.json` to your workspace root and add that path to `.gitignore` to keep credentials out of version control:

```json
{
  "servers": {
    "central-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--prerelease=allow", "central-mcp-server"],
      "env": {
        "CENTRAL_BASE_URL": "your-central-base-url",
        "CENTRAL_CLIENT_ID": "your-client-id",
        "CENTRAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

Add to `.gitignore`:
```
.vscode/mcp.json
```

See the [GitHub CoPilot setup guide](https://developer.arubanetworks.com/new-central/docs/central-github-copilot-setup) for full steps and troubleshooting.

#### HTTP Transport (Streamable HTTP)

By default the server runs over `stdio`, which is the right choice for most MCP clients. If you need to run the server as a persistent HTTP process — for example, to share it across multiple clients or to connect via a remote URL — you can switch to the `streamable-http` transport.

**Step 1 — Install the server as a CLI tool** (if you haven't already):

```bash
uv tool install --prerelease=allow central-mcp-server
```

> `--prerelease=allow` is required because this server depends on `pycentral`, which currently only has a pre-release version on PyPI.

**Step 2 — Create a `.env` file** in your working directory with your credentials and transport settings:

```
CENTRAL_BASE_URL=your-central-base-url
CENTRAL_CLIENT_ID=your-client-id
CENTRAL_CLIENT_SECRET=your-client-secret
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8000
```

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
| `MCP_HOST` | `127.0.0.1` | Host to bind when using HTTP transport |
| `MCP_PORT` | `8000` | Port to listen on when using HTTP transport |

**Step 3 — Start the server:**

```bash
# If installed via uv tool install:
central-mcp-server

# If running from source:
python server.py
```

The MCP endpoint will be available at `http://<MCP_HOST>:<MCP_PORT>/mcp`.

**Step 4 — Connect your MCP client** to the running server:

```bash
claude mcp add central-mcp --transport http --url http://127.0.0.1:8000/mcp
```

Or add it to your MCP client config:

```json
{
  "mcpServers": {
    "central-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

> **Note:** Credentials must be set in the server's environment (via `.env` or OS env vars) before starting it. They are not passed through the HTTP client config.

---

## Supported Capabilities

The server covers eleven capability categories across the new Central REST API families
(Network Monitoring, Network Notifications, Network Troubleshooting):

| Category | What you can ask about |
|---|---|
| Sites & network health | Fleet-wide health overview, per-site metrics |
| Device inventory | All devices, find one by serial/MAC/name |
| Access points | AP lists, per-AP detail, radio/port trends |
| Switches | Switch lists, per-switch detail, hardware/interface trends |
| Gateways | Gateway lists, detail, clusters, capacity trends |
| WLANs | Configured WLANs, per-WLAN throughput |
| Clients | Connected/failed clients, find one by MAC |
| Client analytics | Usage, roaming, and onboarding experience (assoc/auth/dhcp/dns) |
| Alerts | Active alerts per site, by severity/category |
| Events | Event history and counts for a site, device, or client |
| Live troubleshooting | Ping-style tests, show commands, port bounce (with confirmation) |

See the **[Capability Reference](docs/capabilities.md)** for every tool in each category, the
Central API family it uses, and scope/limitations.

## What You Can Ask

Once connected, you can ask your AI assistant questions like:

- *"Give me a health overview of all sites."*
- *"Which sites are in poor health right now?"*
- *"Show me all access points at the Chicago office."*
- *"List the switches in the London campus and show CPU and PoE trends for SG34L5002Y."*
- *"How healthy is the BLR gateway cluster, and what's its client capacity trend?"*
- *"What critical alerts are active across the network?"*
- *"Find all failed wireless clients at HQ in the last 24 hours."*
- *"How is client onboarding doing today, and why are clients failing authentication?"*
- *"What events happened on switch SW-CORE-01 yesterday?"*
- *"Ping 8.8.8.8 from switch SW-CORE-01."*
- *"Run 'show version' and 'show interfaces brief' on switch SG43KN5017."*
- *"Bounce PoE on port 1/1/6 of switch SG43KN5017."*

See [Central MCP Server in Action]((https://developer.arubanetworks.com/new-central/docs/central-mcp-in-action)) for real query examples across all supported clients.

## Example Queries

New to driving an AI assistant over your network? See **[What You Can Ask](docs/what-you-can-ask.md)** — a guided tour of real questions across every tool category (site health, devices, APs, switches, gateways, WLANs, clients, alerts, events, and live diagnostics), each shown with the answer it returns and a list of related questions to try.

### Tool Categories

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'background': '#0b0f1a'}}}%%
graph TD
    MCP["Central MCP Server"] --> Sites["Sites"]
    MCP --> Devices["Device Inventory"]
    MCP --> Clients["Clients"]
    MCP --> Alerts["Alerts"]
    MCP --> Events["Events"]
    MCP --> DevMon["Device Monitoring"]
    MCP --> WLAN["WLAN"]
    MCP --> Troubleshooting["Troubleshooting"]

    classDef mcp fill:#05cc93,color:#001b14,stroke:#000000,stroke-width:2px;
    classDef tool fill:#0070f8,color:#ffffff,stroke:#000000,stroke-width:1.5px;

    class MCP mcp;
    class Sites,Devices,DevMon,Clients,Alerts,Events,WLAN,Troubleshooting tool;

    linkStyle default stroke:#ffffff,stroke-width:2px;
```

### Tools

The 0.2.x surface folds related operations into 13 tools. Envelope-returning reads default to `response_format="concise"`; use `"detailed"` for full item fields.

| Tool | Description |
|------|-------------|
| `central_get_devices` | Browse inventory or family monitoring data; exact serial/name lookup is supported. |
| `central_get_device_details` | Retrieve AP, switch, or gateway detail with family-specific includes. |
| `central_get_device_trends` | Retrieve bounded AP, switch, or gateway time-series samples. |
| `central_get_clients` | Browse filtered clients or look up one exact MAC address. |
| `central_get_client_analytics` | Client usage, roam trail, or per-stage onboarding analytics (`metric` selects the family). |
| `central_get_sites` | Retrieve summary or detailed site health views. |
| `central_get_wlans` | List WLANs or add throughput to one exact SSID. |
| `central_get_gateway_cluster` | Retrieve cluster members, health, and optional capacity/resources. |
| `central_get_events` | Retrieve event records (`mode="records"`) or facets (`mode="facets"`). |
| `central_get_alerts` | Retrieve filtered active, cleared, or deferred alerts for a site. |
| `central_run_network_test` | Run a live network diagnostic (ping, traceroute, http, https, tcp, nslookup) against a device — device family resolved automatically from serial number |
| `central_run_show_commands` | Execute show commands on a device; auto-validates against the device's supported command catalog and returns the catalog on any mismatch |
| `central_bounce_port` | Bounce ports or toggle PoE on CX/AOS-S switches and gateways — fetches live interface state and requires user confirmation before executing |

### LLM Workflow for Events

Use this sequence for faster, lower-token event investigations:

1. For site-level queries, call events tools with `site_id` only.
2. For device/client queries, pass `site_id` plus `context_type` and `context_identifier`.
3. Call `central_get_events` with `mode="facets"` and `response_mode="compact"` to get ranked event names, source types, and categories.
4. Pick the top category/source/event name as your likely starting point.
5. Call `central_get_events` with `mode="records"` and targeted filters to fetch detailed records.
6. Use `mode="facets"`, `response_mode="full"` only when exact per-value counts are required.

### Guided Prompts

The server includes 12 built-in prompts to help AI assistants run common workflows:

| Prompt | Description |
|--------|-------------|
| `network_health_overview` | Full network health overview across all sites |
| `troubleshoot_site` | Deep-dive troubleshooting for a specific site |
| `client_connectivity_check` | Investigate connectivity status for a client by MAC address |
| `investigate_device_events` | Review recent events for a specific device |
| `site_event_summary` | Summarize all events at a site within a time window |
| `failed_clients_investigation` | Find and diagnose all failed clients at a site |
| `site_client_overview` | Overview of client connectivity at a site |
| `device_type_health` | Health check for all devices of a specific type at a site |
| `top_event_drivers` | Identify dominant event drivers at a site and pull supporting evidence |
| `critical_alerts_review` | Review all active critical alerts across the network |
| `wlan_health_check` | Assess WLAN health using client failures and related events over a time window |
| `compare_site_health` | Compare health metrics side-by-side across multiple sites |

---

## Dev Setup

```bash
git clone <Github Server URL>
cd central-mcp-server
```

Create and activate a virtual environment, then install dependencies:

```bash
python3 -m venv .venv
source .venv/bin/activate
uv sync
```

Create `.env` with your credentials:

```
CENTRAL_BASE_URL=your-central-base-url
CENTRAL_CLIENT_ID=your-client-id
CENTRAL_CLIENT_SECRET=your-client-secret
```

Run the server:

```bash
python3 server.py
```

To install and test the package locally before publishing:

```bash
uv tool install .
```