convez.ai
MCP ServerIntegração & APIsAvançado
Nandi-Pura

Aruba ClearPass MCP Server

Nandi-Pura/Aruba-Clearpass-MCP-Server

IA nativa para gerenciar Aruba ClearPass via linguagem natural

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que integra Aruba ClearPass Policy Manager com assistentes IA (Claude, Cursor), permitindo consultas e gerenciamento em linguagem natural. Suporta operações como busca de endpoints por MAC, investigação de sessões ativas, provisionamento de contas guest e verificações de saúde do sistema.

Instalação

$npx convez-ai Nandi-Pura/Aruba-Clearpass-MCP-Server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Consultar endpoints e sessões ativas via linguagem natural
  • Provisionar contas guest e gerenciar políticas de acesso
  • Automatizar health checks e auditoria de ClearPass
  • Integrar ClearPass em workflows de IA para operações de rede

Veredito

MCP server bem arquitetado e robusto para integração de Aruba ClearPass com IA. Ideal para operadores de rede que buscam automação de tarefas administrativas via linguagem natural, mas requer conhecimento sólido de ClearPass, OAuth2 e operações de infraestrutura.

README

A tradução para o português deste README ainda está na fila.

🛡️ Aruba ClearPass MCP Server

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 — look up endpoints by MAC, investigate active sessions, provision guest accounts, run health checks, and more.


Architecture

graph LR
    A["AI Client<br/>(Claude Desktop / Code)"]
    B["clearpass-mcp<br/>MCP Server<br/>(stdio or SSE)"]
    C["OAuth2 Token Cache<br/>(asyncio.Lock)"]
    D["Aruba ClearPass CPPM<br/>REST API (HTTPS)"]
    E["audit.jsonl<br/>(optional)"]

    A -->|"MCP stdio / SSE"| B
    B -->|"client_credentials grant"| C
    C -.->|"Bearer token"| B
    B -->|"HTTPS REST API"| D
    D -->|"JSON responses"| B
    B -->|"Tool results"| A
    B -->|"Write audit events"| E

Key technical properties:

  • Single persistent httpx.AsyncClient (connection pooling, no per-request overhead)
  • asyncio.Lock prevents thundering-herd duplicate token refreshes
  • Automatic 401 → token refresh → retry cycle
  • Tenacity retry with exponential backoff for 5xx / timeouts (3 attempts, 1–10 s)
  • Paginated list endpoints via _links.next following (configurable max_pages)
  • Structured JSON audit log for all write operations (redacts secrets automatically)

Quick Start

Install from source (recommended)

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)

# Requires Python 3.10+ and uv installed
uvx --from git+https://github.com/Nandi-Pura/Aruba-Clearpass-MCP-Server clearpass-mcp --check

Note: uvx clearpass-mcp (without --from git+...) will be available once this package is published to PyPI. Until then, use the git+https form above or install from source.

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_MAX_PAGES=20

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

Cursor IDE

  1. Open Cursor Settings > Features > MCP.
  2. Click + Add New MCP Server.
  3. Configure as follows:
    • Type: command
    • Name: ClearPass
    • Command: clearpass-mcp
  4. Click Save. (Note: Ensure your Cursor instance has access to the required CLEARPASS_* environment variables, or use a .env file in your workspace).

VS Code (Cline / Roo Code)

Access your MCP settings file via the extension's panel or Command Palette, and add:

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

Windsurf IDE

Add the same JSON configuration block from above to your ~/.codeium/windsurf/mcp_config.json file and restart Windsurf.

Claude Desktop

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

From source (pip install -e . must have been run first — this puts clearpass-mcp on PATH inside the venv):

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

Alternatively, reference the Python module directly (no PATH requirement):

{
  "mcpServers": {
    "clearpass": {
      "command": "/path/to/venv/python",
      "args": ["-m", "clearpass_mcp"],
      "env": {
        "CLEARPASS_HOST": "https://clearpass.yourdomain.com",
        "CLEARPASS_CLIENT_ID": "your_client_id",
        "CLEARPASS_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

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

Typed Tools (Phase 4 — recommended for common workflows)

ToolCategoryR/Wconfirm requiredDescription
find_endpoint_by_macIdentitiesR—Look up endpoint by MAC address. Normalises colons/hyphens/bare hex automatically.
get_endpoint_insightLogs & AuditR—Retrieve ClearPass Insight analytics for a MAC or IP address.
list_active_sessionsSession ControlR—Paginated list of active RADIUS/802.1X sessions, with optional filter dict.
disconnect_sessionSession ControlW✅Disconnect a single active session. Requires confirm=True. Supports dry_run.
bulk_coaSession ControlW✅Send a Change-of-Authorization to sessions matching a filter. Supports dry_run.
create_guest_accountIdentitiesW—Create a time-limited guest account. Auto-calculates expire_time. Supports dry_run.
get_server_healthServer ConfigR—Aggregated cluster health: versions, node list, FIPS mode.
search_audit_recordsLogs & AuditR—Paginated audit record search with time range and optional category filter.

Generic Proxy Tools (escape hatch — any endpoint)

ToolMethodDescription
clearpass_getGETQuery any ClearPass endpoint with optional params
clearpass_postPOSTCreate resources or trigger actions. Supports dry_run.
clearpass_patchPATCHPartial update any resource. Supports dry_run.
clearpass_putPUTFull resource replacement. Supports dry_run.
clearpass_deleteDELETEDelete any resource. Requires confirm=True. Supports dry_run.
clearpass_list_apis—Browse the static endpoint catalog with optional category filter.

Tip: Use clearpass_list_apis first to discover the available endpoints for a given category (e.g. "SessionControl", "PolicyElements", "GuestActions").


MCP Resources & Prompts

Resource

URIDescription
clearpass://api-catalogFull endpoint catalog (JSON) — load for endpoint discovery without a tool call

Guided Prompts

PromptParametersUse case
investigate_device_by_macmac_addressMulti-step device investigation (endpoint + sessions + Insight)
onboard_guest_accountvisitor_name, contact_email, valid_hoursGuided guest provisioning with dry-run step
quarantine_endpointmac_addressInvestigate → confirm → disconnect suspicious device
daily_cluster_health_check—Health, licenses, audit summary, and system events

Security

Read-Only Mode

Set CLEARPASS_READ_ONLY=true to prevent all write operations at the server level. Recommended for monitoring integrations where no changes should be made.

CLEARPASS_READ_ONLY=true clearpass-mcp

Dry-Run Mode

Every write tool supports dry_run=True. When enabled:

  • The intended HTTP request is logged (with body redacted) to the audit log
  • A preview dict is returned showing exactly what would have been sent
  • No request is made to ClearPass

Always use dry_run=True first when working with unfamiliar tools or large datasets.

Audit Logging

All write operations (POST/PATCH/PUT/DELETE) emit a structured JSON line to stderr and optionally to a file:

{
  "timestamp": "2024-01-15T09:30:00+00:00",
  "tool": "create_guest_account",
  "method": "POST",
  "path": "/guest",
  "body": {"username": "alice@example.com", "password": "[REDACTED]", "role_id": 5},
  "dry_run": false,
  "outcome": "success",
  "status_code": 201
}

Keys containing secret, password, token, key, or credential are automatically redacted.

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. Disabling certificate verification exposes you to man-in-the-middle attacks. Only disable in isolated lab environments.

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 using super_admin API clients.


Relation to pyclearpass

This server is complementary to, not a replacement for, the official pyclearpass SDK maintained by Aruba:

clearpass-mcppyclearpass
PurposeAI-assistant integration via MCPGeneral Python scripting / automation
InterfaceNatural language → MCP toolsPython function calls
AuthOAuth2 client_credentialsOAuth2 (multiple grant types)
StatusCommunity-maintained (MIT)Official Aruba SDK (Apache 2.0)

For scripting and automation outside an AI context, use pyclearpass. For integrating ClearPass into Claude, Cursor, or other MCP clients, use this server.


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
pytest

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

Acknowledgements

  • Aruba ClearPass REST API Guide — the authoritative source for all endpoint paths, request/response schemas, and authentication flows documented in this server.
  • pyclearpass — the official Aruba Python SDK for ClearPass, which served as a reference for API structure and endpoint organisation.
  • The MCP Python SDK — the upstream FastMCP framework that powers this server's tool and resource registration.
  • The broader Aruba MCP community (aruba-central-mcp, central-mcp-server, aruba-cx-mcp-server) for establishing the patterns this project follows.

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

Ver o original no GitHub

Bom para

Relacionados