Aruba Clearpass

CI Python 3.10+ License: MIT MCP Community

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.

Why this server?

This project turns Aruba ClearPass Policy Manager into an AI-usable operation catalog. Instead of hardcoding a small subset of endpoints, it exposes the full ClearPass REST API surface through two MCP tools:

• clearpass_discover — browse the operation catalog, filter by category/keyword/type
• clearpass_invoke — safely invoke the selected operation with typed parameters

This makes the server a good fit for workflow automation, troubleshooting, guest/session inspection, and operator-assisted policy management in MCP-enabled clients such as Cline, Claude Desktop, Cursor, and Windsurf.

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<br/>(Claude Desktop / Code)"]
    B["clearpass-mcp<br/>MCP Server<br/>(stdio or SSE)"]
    C["pyclearpass SDK<br/>(per-class singletons)"]
    D["Aruba ClearPass CPPM<br/>REST API (HTTPS)"]
    E["audit.jsonl<br/>(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.

For Cline on Windows, a direct Python-module form is the most reliable option:

{
  "mcpServers": {
    "clearpass": {
      "command": "C:/Program Files/Python314/python.exe",
      "args": ["-m", "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"
      }
    }
  }
}

To verify the server can authenticate before connecting it to your MCP client:

cd Aruba-Clearpass-MCP-Server
& "C:/Program Files/Python314/python.exe" -m clearpass_mcp --check

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": "[email protected]", "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 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 © 2024 Nandi-Pura