ClearPass Sidekick MCP Server

A Model Context Protocol (MCP) server that enables natural language automation of Aruba ClearPass configuration tasks through LLM clients like Claude.

Overview

ClearPass Sidekick bridges the gap between natural language commands and ClearPass API operations, allowing network administrators to manage ClearPass configurations through conversational interfaces. The system leverages the Model Context Protocol to provide structured tool access to ClearPass APIs.

Related MCP server: HPE Aruba Networking Central MCP Server

Architecture

+---------------------+       Natural Language        +----------------------+
|  User / LLM Client  | <---------------------------->|      MCP Client      |
|  (e.g., Claude)     |   (structured tool call)      | (e.g., Claude Desktop)|
+---------------------+                               +----------+-----------+
                                                             |
                                                             | (via stdio or SSE)
                                                             v
                                                  +----------------------+
                                                  |      MCP Server      |
                                                  |  (Python/Typescript) |
                                                  +----------+-----------+
                                                             |
                                          ClearPass API Client Module
                                                             |
                                                             v
                                                  +----------------------+
                                                  |  Aruba ClearPass API |
                                                  |  (REST endpoints)    |
                                                  +----------------------+

Progressive Disclosure Architecture

ClearPass Sidekick supports 761 distinct ClearPass operations — full endpoint parity with Aruba's pyclearpass 1.0.8 SDK (801/801 endpoints), plus operations beyond it. Exposing all 761 as individual MCP tools means the LLM must load 761 full tool schemas into its context window on every request — tens of thousands of tokens of parameter definitions the model rarely needs all at once. That crowds out the user's actual task, slows responses, and degrades tool-selection accuracy.

To solve this, the server uses progressive disclosure: instead of 761 direct tools, default mode exposes just 7 direct tools — 3 gateway meta-tools plus 4 server_utility tools. All 761 operations remain fully available; 757 are reached on demand through the gateway, and the 4 utility tools stay direct.

The Three Gateway Meta-Tools

Typical Flow

1. list_operations(search="guest account")
     -> [{ name: "create_guest_user", domain: "guest_users", summary: "..." }, ...]

2. describe_operations(names=["create_guest_user"])
     -> full parameter schema for create_guest_user

3. invoke_operation(name="create_guest_user", params={ "username": "visitor01", ... })
     -> operation result

The model loads only the schemas it actually needs, keeping the context window lean while retaining the full operation catalog.

Legacy Mode

To restore the pre-refactor behavior (every operation registered as its own direct @mcp.tool()), set the environment variable:

CLEARPASS_MCP_LEGACY_TOOLS=true

In legacy mode the server registers all 757 domain operations as direct tools in addition to the 7 default tools (764 total) and logs Legacy mode: registered 757 direct tools at startup. Leave this false (the default) unless a client cannot use the gateway pattern.

Features

• Natural Language Interface: Issue commands in plain English to manage ClearPass configurations

• Comprehensive API Coverage: Support for API clients, devices, endpoints, guest management, guest portals, and certificates

• OAuth2 Authentication: Secure authentication using client credentials grant

• Audit Logging: Complete audit trail of all automated changes

• Error Handling: Detailed error messages and confirmation prompts for ambiguous operations

Use Cases

Core Network Management

• API Client Management: "Create an API client named 'automation-bot' with read-only privileges"

• Network Device Operations: "Show me all network devices with CoA enabled" or "Add a new Aruba switch with IP 192.168.1.100"

• Guest User Management: "Extend guest user 'visitor01' by 24 hours" or "Create a guest account for contractor access"

Guest Portal & Credential Delivery

• Digital Passes: "Generate an Apple Wallet pass for guest user 'visitor01'" or "Create a Google Pay pass for conference attendees"

• Receipt Generation: "Generate a printable receipt for guest 'contractor-john'" or "Create HTML receipt for email delivery"

• Credential Delivery: "Send guest credentials via SMS" or "Email the WiFi password to the visitor"

• Sponsor Workflows: "Approve the pending guest access request" or "Reject unauthorized guest registration"

• Portal Customization: "List all web login pages" or "Create a new captive portal for the lobby"

• Template Management: "Update the guest receipt template" or "Create a new digital pass template with company branding"

Advanced Policy Management

• Enforcement Profiles: "Create a corporate employee profile using the template" or "List all active enforcement policies"

• Authentication Methods: "Configure EAP-TLS authentication for wireless users"

• Role Management: "Create a contractor role with limited network access"

• Configuration Services: "Set up RADIUS authentication source for Active Directory"

Session Control & Monitoring

• Active Session Management: "Show me all active user sessions" or "Disconnect sessions for user 'jdoe'"

• Change of Authorization: "Perform CoA to update user policies immediately"

• Audit & Compliance: "Show me login audit records for the past week"

Certificate & Security Operations

• Certificate Lifecycle: "Issue a certificate for device 'switch-01'" or "Generate CSR for new server"

• Trust Management: "Import certificate to trust list" or "Validate certificate configuration"

Server Configuration

• Global Settings: "Configure SNMP trap receivers" or "Manage application licenses"

• Local Configuration: "Join server to Active Directory domain" or "Configure cluster parameters"

• Administrative Tasks: "Create admin user with operator privileges" or "Update password policies"

Prerequisites

• Python 3.8 or higher

• Access to an Aruba ClearPass Policy Manager instance

• ClearPass API client credentials (OAuth2)

• LLM client supporting MCP (e.g., Claude Desktop)

Installation

1. Clone the repository:

   git clone https://github.com/cheddarking/clearpass-sidekick-mcp.git
   cd clearpass-sidekick-mcp

2. Create and activate virtual environment:

   python -m venv .venv
   
   # On Windows
   .venv\Scripts\activate
   
   # On macOS/Linux
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure ClearPass credentials:

   Set the following environment variables:

   export CLEARPASS_SERVER=https://your-clearpass-server.com:443/api
   export CLEARPASS_CLIENT_ID=your-oauth-client-id
   export CLEARPASS_CLIENT_SECRET=your-oauth-client-secret
   export CLEARPASS_VERIFY_SSL=true

   Or use API token authentication:

   export CLEARPASS_SERVER=https://your-clearpass-server.com:443/api
   export CLEARPASS_API_TOKEN=your-pre-generated-api-token
   export CLEARPASS_VERIFY_SSL=true

Configuration

ClearPass Sidekick uses environment variables for authentication. You can use either OAuth2 client credentials or API token authentication:

OAuth2 Client Credentials

CLEARPASS_SERVER=https://your-clearpass-server.com:443/api
CLEARPASS_CLIENT_ID=your-oauth-client-id  
CLEARPASS_CLIENT_SECRET=your-oauth-client-secret
CLEARPASS_VERIFY_SSL=true  # Optional, defaults to true

API Token Authentication

CLEARPASS_SERVER=https://your-clearpass-server.com:443/api
CLEARPASS_API_TOKEN=your-pre-generated-api-token
CLEARPASS_VERIFY_SSL=true  # Optional, defaults to true

Usage

Docker Setup (Recommended)

The easiest way to use ClearPass Sidekick is with the pre-built Docker image. Configure it directly in your MCP client settings - no need to run Docker commands separately.

For Claude Desktop

Add this to your Claude Desktop configuration file:

Using OAuth2 Client Credentials:

{
  "mcpServers": {
    "clearpass-sidekick": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CLEARPASS_SERVER=https://your-clearpass-server.com:443/api",
        "-e", "CLEARPASS_CLIENT_ID=your-oauth-client-id",
        "-e", "CLEARPASS_CLIENT_SECRET=your-oauth-client-secret",
        "-e", "CLEARPASS_VERIFY_SSL=true",
        "bicharri/clearpass-sidekick:latest"
      ]
    }
  }
}

Using API Token:

{
  "mcpServers": {
    "clearpass-sidekick": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CLEARPASS_SERVER=https://your-clearpass-server.com:443/api",
        "-e", "CLEARPASS_API_TOKEN=your-api-token",
        "-e", "CLEARPASS_VERIFY_SSL=true",
        "bicharri/clearpass-sidekick:latest"
      ]
    }
  }
}

The Docker image will be automatically pulled if not present. Claude Desktop will start and manage the container lifecycle automatically.

Local Python Setup (Development)

For development or if you prefer running from source:

1. Follow the Installation steps

2. Configure your MCP client:

{
  "mcpServers": {
    "clearpass-sidekick": {
      "command": "python",
      "args": ["/path/to/your/project/src/main.py"],
      "env": {
        "CLEARPASS_SERVER": "https://your-clearpass-server.com:443/api",
        "CLEARPASS_CLIENT_ID": "your-oauth-client-id",
        "CLEARPASS_CLIENT_SECRET": "your-oauth-client-secret",
        "CLEARPASS_VERIFY_SSL": "true"
      }
    }
  }
}

Manual Docker Run (Optional)

If you need to run the Docker container manually for testing:

docker run --rm -i \
  -e CLEARPASS_SERVER="https://your-clearpass-server.com:443/api" \
  -e CLEARPASS_CLIENT_ID="your-oauth-client-id" \
  -e CLEARPASS_CLIENT_SECRET="your-oauth-client-secret" \
  bicharri/clearpass-sidekick:latest

Available Operations

The server provides 761 ClearPass operations across 20 specialized domains. In default mode these are reached through the gateway meta-tools (see Progressive Disclosure Architecture above) rather than being registered as 761 individual tools. The domains and their operation groups:

Core ClearPass Management (84 operations)

• API Client Management (5 operations): Complete CRUD operations for OAuth API clients

• Network Device Management (16 operations): NAD configuration with RADIUS/TACACS+ support

• Guest User Management (5 operations): Temporary access provisioning with sponsor workflows

• Guest Actions (5 operations): Digital pass generation, receipt printing, SMS/email credential delivery, sponsor approval workflows

• Guest Configuration (28 operations): Pass templates, print templates, web login pages, authentication settings, guest manager configuration

• Certificate Operations (9 operations): CSR generation, trust lists, client/server certificates, CA operations

• Audit & Logging (12 operations): System events, login audits, insight alerts, comprehensive API operation tracking

• Server Utility (4 direct tools): Connection testing, configuration validation, health monitoring (always registered as direct MCP tools)

Advanced Server Configuration (73 operations)

• Global Server Configuration (58 operations): Admin users, privileges, licenses, attributes, data filters, operator profiles, SNMP, messaging, backup servers, policy manager zones

• Local Server Configuration (15 operations): Access control, Active Directory integration, cluster management (list_cluster_servers supplies the server_uuid the other cluster operations need), version info

Session & Network Control (14 operations)

• Session Control (14 operations): Active session monitoring, disconnect operations, reauthorization, Change of Authorization (CoA)

Policy Engine Components (120 operations)

• Policy Elements (112 operations): The largest implementation covering:

  • Core Components: Roles, role mappings, enforcement policies, configuration services

  • Authentication: Methods (EAP, certificates), sources (AD/LDAP integration)

  • Network Infrastructure: Device groups, enhanced device configuration (SNMP, RadSec, CLI)

  • Advanced Policies: Posture policies, RADIUS dynamic authorization templates

  • Dictionaries: Application and RADIUS custom attribute definitions

  • Specialized: Proxy targets (RADIUS proxy), TACACS+ service dictionaries

• Enforcement Profiles (8 operations): Basic profile management with template-based creation for common networking scenarios

Enterprise Features

• Template-Driven Configuration: Predefined templates for corporate, guest, contractor, IoT, and executive access

• Bulk Operations: Mass updates and configuration changes with safety confirmations

• Advanced Search & Filtering: Multi-criteria search across all components

• Validation & Testing: Configuration validation, connectivity testing, dependency checking

• Statistics & Analytics: Usage monitoring, performance metrics, compliance reporting

Development

Project Structure

clearpass-sidekick/
├── src/                    # Source code
│   ├── registry.py        # Operation registry (progressive disclosure)
│   ├── tools/             # 761 operations: 757 registry ops + 4 direct tools
│   │   ├── gateway.py            # 3 gateway meta-tools (list/describe/invoke)
│   │   ├── server_utility.py     # 4 direct @mcp.tool utilities
│   │   ├── guest_actions.py      # Guest credential delivery (5 operations)
│   │   ├── guest_configuration.py # Portal & template management (28 operations)
│   │   └── ...                   # Other domain modules (@operation registry)
│   ├── client_methods/    # API interaction mixins
│   ├── models/            # Pydantic data models
│   ├── clearpass_client.py # Main API client
│   ├── credentials.py     # Secure credential management
│   ├── app_config.py      # Application configuration
│   └── main.py           # MCP server entry point
├── docs/                  # Implementation plans and documentation
├── tests/                 # Test files
├── scripts/               # PRD and utility scripts
├── requirements.txt       # Python dependencies
└── README.md             # This file

Running Tests

The offline suite is hermetic — no network, no credentials — and reports 222 passed, 0 failed:

python -m pytest tests/ --ignore=tests/live

Live Validation

tests/live/ holds an opt-in harness that exercises the server against a real ClearPass appliance. It is skipped at collection time unless --live is passed, so the normal suite stays offline and fast; running it requires a reachable appliance and credentials in the environment:

set -a; . .env; set +a
python -m pytest tests/live --live -q -s

It is safe to point at a lab appliance. Every object it creates is namespaced zzz-mcptest-*, and writes and deletes only ever target that prefix; an 18-operation denylist is never dispatched live (deleting the sole API client would revoke the harness's own access, deleting admin users risks lockout, and the guest SMS/email receipt operations send to real recipients); and a before/after inventory snapshot diff fails the run if anything outside the prefix changed. Calls route through invoke_operation, so a live run validates the progressive-disclosure dispatch path alongside the operations themselves.

The 2026-07-30 full-coverage run exercised all 757 registry operations (711 live tests passed, 0 failed) against a ClearPass 6.12.4 lab appliance with zero drift to pre-existing objects. See tests/live/README.md for the full contract.

Code Style

This project follows PEP 8 style guidelines. Use the following tools for code quality:

# Format code
black src/

# Lint code
flake8 src/

# Type checking
mypy src/

Security Considerations

• OAuth2 Authentication: All API calls use secure OAuth2 client credentials

• HTTPS Transport: All communications use TLS 1.2+

• Credential Storage: Store sensitive credentials in secure vaults

• Audit Logging: Complete audit trail of all operations

• Input Validation: Comprehensive validation of all user inputs

API References

• ClearPass Policy Manager REST API: Developer Documentation

• PyClearPass SDK: GitHub Repository

• Model Context Protocol: Official Documentation

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

• Create an issue in this repository

• Check the ClearPass API documentation

• Review the MCP documentation

Acknowledgments

• Aruba Networks for the ClearPass API

• Anthropic for the Model Context Protocol

• The open-source community for various dependencies