Aruba Clearpass MCP Server

🛡️ 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 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

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

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)

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:

cp .env.example .env

# 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

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):

{
  "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)

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

Or with Docker:

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:

{
  "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:

{
  "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.

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:

{
  "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:

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.

# 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 — the official Aruba Python SDK

for ClearPass, now used as the sole communication layer in this server.

• Aruba ClearPass REST API Guide

— the authoritative source for all endpoint paths, request/response schemas, and authentication flows.

• The MCP 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
• Source: Nandi-Pura/Aruba-Clearpass-MCP-Server
• License: MIT

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