# Aruba Clearpass MCP Server

> MCP server from Nandi-Pura/Aruba-Clearpass-MCP-Server.

- **Type:** MCP server
- **Install:** `agentstack add mcp-nandi-pura-aruba-clearpass-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Nandi-Pura](https://agentstack.voostack.com/s/nandi-pura)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Nandi-Pura](https://github.com/Nandi-Pura)
- **Source:** https://github.com/Nandi-Pura/Aruba-Clearpass-MCP-Server

## Install

```sh
agentstack add mcp-nandi-pura-aruba-clearpass-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🛡️ Aruba ClearPass MCP Server

[](https://github.com/Nandi-Pura/Aruba-Clearpass-MCP-Server/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://devhub.arubanetworks.com/code-exchange)

> **Community-maintained MCP server for Aruba ClearPass Policy Manager.**
> Not an official HPE / Aruba Networks product. MIT licensed. Use at your own risk.

Enable AI assistants (Claude, Cursor, Continue.dev, and any MCP-compatible client) to query
and manage your ClearPass Policy Manager using natural language — via the official
[`pyclearpass`](https://github.com/aruba/pyclearpass) SDK.

**v2.0.0** replaces the previous generic HTTP-proxy approach with a two-tool dispatcher
pattern: `clearpass_discover` to browse 816+ operations, and `clearpass_invoke` to execute
any of them. The entire ClearPass v1 REST API surface is available automatically — no
hardcoded endpoint lists.

---

## Architecture

```mermaid
graph LR
    A["AI Client(Claude Desktop / Code)"]
    B["clearpass-mcpMCP Server(stdio or SSE)"]
    C["pyclearpass SDK(per-class singletons)"]
    D["Aruba ClearPass CPPMREST API (HTTPS)"]
    E["audit.jsonl(optional)"]

    A -->|"MCP stdio / SSE"| B
    B -->|"clearpass_discover"| B
    B -->|"clearpass_invoke"| C
    C -->|"client_credentials OAuth2"| D
    D -->|"JSON responses"| C
    C -->|"Tool results"| B
    B -->|"Tool results"| A
    B -->|"Write audit events"| E
```

**Key technical properties:**
- 16 pyclearpass API classes, **816 operations** auto-discovered at startup via `inspect`
- Per-class singleton instances — token fetched once, reused for server lifetime
- Tenacity retry (exponential backoff, 3 attempts) for transient network errors on **read** operations
- No automatic retry for **write** operations (prevents duplicate mutations)
- `confirm_write=True` required for all write/mutating operations
- `CLEARPASS_READ_ONLY=true` blocks all writes at the server level
- Structured JSON audit log for write operations (redacts secrets automatically)
- MAC address masking: OUI preserved, last 3 octets replaced with `xx:xx:xx`

---

## Quick Start

### Install from source

```bash
git clone https://github.com/Nandi-Pura/Aruba-Clearpass-MCP-Server.git
cd Aruba-Clearpass-MCP-Server
pip install -e .
clearpass-mcp --help
```

### Run without cloning (via `uvx`)

```bash
uvx --from git+https://github.com/Nandi-Pura/Aruba-Clearpass-MCP-Server clearpass-mcp --check
```

### Configuration

Copy `.env.example` to `.env` and fill in your values:

```bash
cp .env.example .env
```

```bash
# Required
CLEARPASS_HOST=https://clearpass.yourdomain.com
CLEARPASS_CLIENT_ID=your_api_client_id
CLEARPASS_CLIENT_SECRET=your_api_client_secret

# Optional
CLEARPASS_VERIFY_SSL=true            # false only for lab self-signed certs
CLEARPASS_READ_ONLY=false            # true = monitoring-only, blocks all writes
CLEARPASS_LOG_LEVEL=INFO
CLEARPASS_AUDIT_LOG_PATH=            # e.g. /var/log/clearpass-mcp/audit.jsonl
CLEARPASS_REDACT_SENSITIVE=true      # mask MAC addresses + secret fields in responses
CLEARPASS_TIMEOUT=                   # HTTP timeout in seconds (unset = no timeout)
```

> **ClearPass API client setup:**
> In the ClearPass UI → *Administration → API Services → API Clients*, create a new client
> with *Grant Type: client_credentials* and assign an Operator Profile with appropriate
> permissions (read-only profile for monitoring, API Administrator for full access).

### Validate your configuration

```bash
clearpass-mcp --check
```

Exit codes: `0` = success, `1` = config error, `2` = OAuth2 error.

---

## Client Integration

### Claude Desktop

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

```json
{
  "mcpServers": {
    "clearpass": {
      "command": "clearpass-mcp",
      "env": {
        "CLEARPASS_HOST": "https://clearpass.yourdomain.com",
        "CLEARPASS_CLIENT_ID": "your_client_id",
        "CLEARPASS_CLIENT_SECRET": "your_client_secret",
        "CLEARPASS_VERIFY_SSL": "true",
        "CLEARPASS_READ_ONLY": "false",
        "CLEARPASS_REDACT_SENSITIVE": "true"
      }
    }
  }
}
```

### Cursor IDE

1. Open **Cursor Settings** > **Features** > **MCP**.
2. Click **+ Add New MCP Server**.
3. Configure: Type = `command`, Name = `ClearPass`, Command = `clearpass-mcp`.

### VS Code (Cline / Roo Code) / Windsurf

Use the same JSON block from above in your MCP settings file.

### SSE Transport (remote / multi-user)

```bash
clearpass-mcp --transport sse --host 0.0.0.0 --port 8000
```

Or with Docker:

```bash
docker run -p 8000:8000 \
  -e CLEARPASS_HOST=https://clearpass.yourdomain.com \
  -e CLEARPASS_CLIENT_ID=your_client_id \
  -e CLEARPASS_CLIENT_SECRET=your_client_secret \
  clearpass-mcp --transport sse --host 0.0.0.0 --port 8000
```

---

## Tool Reference

This server exposes exactly **two MCP tools**. All ClearPass operations go through this pair.

### `clearpass_discover` — Browse the operation catalog

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `category` | `str \| null` | `null` (all) | Filter by category (case-insensitive) |
| `keyword` | `str \| null` | `null` | Substring search on name + description |
| `operation_type` | `"read" \| "write" \| "all"` | `"all"` | Filter by operation classification |

**Categories:** `"Identities"`, `"Policy Elements"`, `"Session Control"`, `"Onboard & CA"`, `"OnGuard & Visibility"`, `"Guest Management"`, `"System & Logs"`

**Returns:**
```json
{
  "total": 71,
  "categories": ["Identities"],
  "operations": [
    {
      "operation_id": "identities.get_endpoint",
      "category": "Identities",
      "type": "read",
      "description": "Get a list of endpoints along with its profiling information",
      "parameters": [
        {"name": "filter", "param_type": "query", "required": false, "description": "JSON filter expression", "confidence": "high"},
        {"name": "limit",  "param_type": "query", "required": false, "description": "Maximum number of items", "confidence": "high"}
      ]
    }
  ]
}
```

### `clearpass_invoke` — Execute an operation

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `operation_id` | `str` | **required** | Exact `operation_id` from `clearpass_discover` |
| `params` | `dict` | `{}` | Keyword arguments for the operation |
| `confirm_write` | `bool` | `false` | Set `true` to execute write operations |

**Returns:**
```json
{
  "operation_id": "identities.get_endpoint",
  "type": "read",
  "result": { "items": [...], "_meta": { "total": 42 } },
  "status_code": 200
}
```

---

## Workflow Examples

### Example 1 — Find an endpoint by MAC address

```
User: "Find the endpoint with MAC aa:bb:cc:11:22:33"

AI: clearpass_discover(keyword="endpoint by mac")
 →  finds "identities.get_endpoint_by_mac_address" (read)

AI: clearpass_invoke(
      operation_id="identities.get_endpoint_by_mac_address",
      params={"mac_address": "aa:bb:cc:11:22:33"}
    )
 →  returns endpoint details
```

### Example 2 — Disconnect an active session (write with confirmation)

```
User: "Disconnect the session for MAC aa:bb:cc:11:22:33"

AI: clearpass_discover(keyword="disconnect", operation_type="write")
 →  finds "sessioncontrol.new_session_action_disconnect_mac_by_mac_address"

AI: clearpass_invoke(
      operation_id="sessioncontrol.new_session_action_disconnect_mac_by_mac_address",
      params={"mac_address": "aa:bb:cc:11:22:33"}
    )
 →  REJECTED — "Write operation ... requires explicit confirmation.
               Call again with confirm_write=true to execute."

User: "Yes, proceed"

AI: clearpass_invoke(
      operation_id="sessioncontrol.new_session_action_disconnect_mac_by_mac_address",
      params={"mac_address": "aa:bb:cc:11:22:33"},
      confirm_write=True
    )
 →  session disconnected
```

### Example 3 — Browse all guest management operations

```
AI: clearpass_discover(category="Guest Management", operation_type="all")
 →  returns 33 operations (ApiGuestActions + ApiGuestConfiguration)
```

---

## Security

### Read-Only Mode

Set `CLEARPASS_READ_ONLY=true` to block all write operations at the server level,
regardless of `confirm_write`. Recommended for monitoring-only integrations.

```bash
CLEARPASS_READ_ONLY=true clearpass-mcp
```

### Write Confirmation Gate

Every `type="write"` operation requires `confirm_write=true` in `clearpass_invoke`.
If omitted, the server safely describes what *would* happen and asks for confirmation.
This applies even when `CLEARPASS_READ_ONLY=false`.

### Sensitive Data Redaction

When `CLEARPASS_REDACT_SENSITIVE=true` (default):
- **MAC addresses:** last 3 octets replaced with `xx:xx:xx` (OUI preserved for vendor identification)
- **Secret fields:** keys matching `password`, `secret`, `token`, `key`, `credential`, `psk`, etc. → `"[REDACTED]"`

### Audit Logging

All write operations emit a structured JSON line to stderr and optionally to a file:

```json
{
  "timestamp": "2024-01-15T09:30:00+00:00",
  "operation_id": "guestconfiguration.new_guest",
  "type": "write",
  "params": {"username": "alice@example.com", "password": "[REDACTED]"},
  "outcome": "success",
  "status_code": 201
}
```

Enable file logging:

```bash
CLEARPASS_AUDIT_LOG_PATH=/var/log/clearpass-mcp/audit.jsonl clearpass-mcp
```

### TLS / SSL

Always keep `CLEARPASS_VERIFY_SSL=true` in production.

### Principle of Least Privilege

Create a dedicated API client in ClearPass with an Operator Profile that grants only the
permissions your use case requires. Avoid `super_admin` API clients.

---

## Migration Guide (v1 → v2)

> **v2.0.0 is a breaking change.** The tool interface has changed completely.

### Environment variables — unchanged ✅

All existing environment variables continue to work without modification:
`CLEARPASS_HOST`, `CLEARPASS_CLIENT_ID`, `CLEARPASS_CLIENT_SECRET`,
`CLEARPASS_VERIFY_SSL`, `CLEARPASS_READ_ONLY`, `CLEARPASS_LOG_LEVEL`,
`CLEARPASS_AUDIT_LOG_PATH`.

**New in v2:**
- `CLEARPASS_REDACT_SENSITIVE=true` (default: true) — response data masking
- `CLEARPASS_TIMEOUT` — HTTP timeout in seconds

**Removed in v2:**
- `CLEARPASS_MAX_PAGES` — pagination is now handled by ClearPass natively via pyclearpass

### Command / entrypoint — unchanged ✅

`clearpass-mcp` command name and `python -m clearpass_mcp` remain the same.

### Tools — breaking change ⚠️

| v1 tool | v2 equivalent |
|---------|--------------|
| `clearpass_get` | `clearpass_invoke(operation_id="...", params={...})` |
| `clearpass_post` | `clearpass_invoke(operation_id="...", params={...}, confirm_write=True)` |
| `clearpass_patch` | `clearpass_invoke(operation_id="...", params={...}, confirm_write=True)` |
| `clearpass_put` | `clearpass_invoke(operation_id="...", params={...}, confirm_write=True)` |
| `clearpass_delete` | `clearpass_invoke(operation_id="...", params={...}, confirm_write=True)` |
| `clearpass_list_apis` | `clearpass_discover(category="...", keyword="...")` |
| `find_endpoint_by_mac` | `clearpass_invoke(operation_id="identities.get_endpoint_by_mac_address", ...)` |
| `list_active_sessions` | `clearpass_invoke(operation_id="sessioncontrol.get_session", ...)` |
| `disconnect_session` | `clearpass_invoke(operation_id="sessioncontrol.new_session_by_id_disconnect", ..., confirm_write=True)` |
| `create_guest_account` | `clearpass_invoke(operation_id="guestconfiguration.new_guest", ..., confirm_write=True)` |
| `get_server_health` | `clearpass_invoke(operation_id="localserverconfiguration.get_cluster_server", ...)` |
| `search_audit_records` | `clearpass_invoke(operation_id="logs.get_audit_record", ...)` |

---

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and PR guidelines.

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check .

# Type check
mypy src

# Tests (offline — no real ClearPass needed)
pytest

# Validate config against a real ClearPass instance
clearpass-mcp --check

# End-to-end smoke test (requires real ClearPass credentials in .env)
python scripts/smoke_test.py
```

---

## Coverage: pyclearpass vs ClearPass API

`pyclearpass` v1.0.8 provides **816 operations** across **16 API classes**:

| Category | Classes | Operations |
|----------|---------|-----------|
| Identities | ApiIdentities | 71 |
| Policy Elements | ApiPolicyElements + ApiEnforcementProfile | 297 |
| Session Control | ApiSessionControl | 16 |
| Onboard & CA | ApiCertificateAuthority + ApiPlatformCertificates | 48 |
| OnGuard & Visibility | ApiEndpointVisibility + ApiInsight | 128 |
| Guest Management | ApiGuestActions + ApiGuestConfiguration | 33 |
| System & Logs | ApiLogs + ApiLocalServerConfiguration + ApiGlobalServerConfiguration + ApiApiOperations + ApiIntegrations + ApiToolsAndUtilities | 223 |

This is the complete pyclearpass surface — equivalent to the full ClearPass v1 REST API.

---

## Acknowledgements

- [`pyclearpass`](https://github.com/aruba/pyclearpass) — the official Aruba Python SDK
  for ClearPass, now used as the sole communication layer in this server.
- [Aruba ClearPass REST API Guide](https://developer.arubanetworks.com/aruba-cppm/reference)
  — the authoritative source for all endpoint paths, request/response schemas, and
  authentication flows.
- The [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) — the upstream
  `FastMCP` framework that powers this server's tool and resource registration.

---

## Disclaimer

This is a community project and is **not** affiliated with, endorsed by, or supported by
Hewlett Packard Enterprise (HPE) or Aruba Networks. It is provided "as is" under the MIT
license. Always test in a non-production environment before deploying against a live
ClearPass cluster.

---

## License

[MIT](LICENSE) © 2024 Nandi-Pura

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Nandi-Pura](https://github.com/Nandi-Pura)
- **Source:** [Nandi-Pura/Aruba-Clearpass-MCP-Server](https://github.com/Nandi-Pura/Aruba-Clearpass-MCP-Server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nandi-pura-aruba-clearpass-mcp-server
- Seller: https://agentstack.voostack.com/s/nandi-pura
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.