使用说明

🛡️ Aruba ClearPass MCP服务器

社区维护的Aruba ClearPass策略管理器MCP服务器。 不是HPE/Aruba Networks的官方产品。麻省理工学院许可。使用风险自负。

启用AI助手（Claude、Cursor、Continue.dev和任何兼容MCP的客户端）进行查询并通过官方网站使用自然语言管理您的ClearPass策略管理器 pyclearpass SDK。

为什么是这个服务器？

该项目将Aruba ClearPass策略管理器变成了一个AI可用的操作目录。它没有对一小部分端点进行硬编码，而是公开了完整的ClearPass REST API 通过两个MCP工具进行表面处理：

clearpass_discover --浏览操作目录，按类别/关键字/类型筛选
clearpass_invoke --使用类型化参数安全地调用所选操作

这使得服务器非常适合工作流自动化、故障排除、访客/会话在诸如Cline的启用MCP的客户端中执行策略管理、检查和操作员辅助策略管理，克劳德桌面、光标和风帆。

v2.0.0版本 用双工具调度器替换之前的通用HTTP代理方法图案： clearpass_discover 浏览816+个操作，以及 clearpass_invoke 执行他们中的任何一个。整个ClearPass v1 REST API表面可自动使用-无硬编码端点列表。

建筑学

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

关键技术特性：

16个pyclearpass API类， 816次操作 通过启动时自动发现 inspect
每类单例实例——令牌提取一次，在服务器生命周期内重复使用
暂时网络错误的持久重试（指数回退，3次尝试）读运营
没有自动重试写操作（防止重复突变）
confirm_write=True 所有写入/修改操作都需要
CLEARPASS_READ_ONLY=true 阻止服务器级别的所有写入
用于写操作的结构化JSON审计日志（自动编辑机密）
MAC地址掩码：保留OUI，最后3个八位字节替换为 xx:xx:xx

快速开始

从源代码安装

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

运行时不进行克隆（通过 `uvx`)

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

配置

复制 .env.example 到 .env 并填写您的值：

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客户端设置： 在ClearPass用户界面中→ 行政→ API 服务→ API客户端，创建新客户端与 授权类型：client_credentials 并为操作员配置文件分配适当的权限（用于监视的只读配置文件，用于完全访问的API管理员）。

验证您的配置

clearpass-mcp --check

退出代码： 0 =成功， 1 =配置错误， 2 =OAuth2错误。

客户端集成

Claude 桌面版

增添 %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/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"
      }
    }
  }
}

光标IDE

打开 光标设置 > 特性 > 主控程序.
点击 +添加新的MCP服务器.
配置：类型= command，姓名= ClearPass，命令= clearpass-mcp.

VS代码（Cline/Roo代码）/风帆

在MCP设置文件中使用上述相同的JSON块。

对于Windows上的Cline来说，直接的Python模块形式是最可靠的选择：

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

要验证服务器在连接到MCP客户端之前是否可以进行身份验证，请执行以下操作：

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

SSE传输（远程/多用户）

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

或者使用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

工具参考

此服务器完全公开 两个MCP工具。所有ClearPass操作都通过这一对。

`clearpass_discover` --浏览操作目录

参数	类型	默认值	说明
`category`	`str \| null`	`null` （all）	按类别筛选（不区分大小写）
`keyword`	`str \| null`	`null`	按名称+描述进行子字符串搜索
`operation_type`	`"read" \| "write" \| "all"`	`"all"`	按操作分类过滤

类别： "Identities", "Policy Elements", "Session Control", "Onboard & CA", "OnGuard & Visibility", "Guest Management", "System & Logs"

退货：

{
  "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` --执行操作

参数	类型	默认值	说明
`operation_id`	`str`	必需的	精确 `operation_id` 来自 `clearpass_discover`
`params`	`dict`	`{}`	操作的关键字参数
`confirm_write`	`bool`	`false`	设置 `true` 执行写入操作

退货：

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

工作流示例

示例1——通过MAC地址查找端点

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

示例2——断开活动会话的连接（写入并确认）

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

示例3——浏览所有访客管理操作

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

安全

只读模式

集 CLEARPASS_READ_ONLY=true 为了在服务器级别阻止所有写入操作，不管 confirm_write建议仅用于监控集成。

CLEARPASS_READ_ONLY=true clearpass-mcp

写入确认门

每 type="write" 操作需要 confirm_write=true 在 clearpass_invoke. 如果省略，服务器将安全地描述会发生并要求确认。即使在以下情况下也适用 CLEARPASS_READ_ONLY=false.

敏感数据补救

当 CLEARPASS_REDACT_SENSITIVE=true （默认）：

MAC地址： 最后3个八位字节替换为 xx:xx:xx （OUI保留用于供应商识别）
机密字段： 密钥匹配 password, secret, token, key, credential, psk等等。 → "[REDACTED]"

审计日志

所有写入操作都会向stderr发送一个结构化的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
}

启用文件日志记录：

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

TLS/SSL

永远保持 CLEARPASS_VERIFY_SSL=true 在生产中。

最小特权原则

在ClearPass中创建一个专用的API客户端，其操作员配置文件仅授予您的用例所需的权限。避免 super_admin API客户端。

迁移指南（v1→ v2)

v2.0.0是一个突破性的变化。 工具界面已完全更改。

环境变量--未更改✅

所有现有的环境变量继续工作，无需修改： CLEARPASS_HOST, CLEARPASS_CLIENT_ID, CLEARPASS_CLIENT_SECRET, CLEARPASS_VERIFY_SSL, CLEARPASS_READ_ONLY, CLEARPASS_LOG_LEVEL, CLEARPASS_AUDIT_LOG_PATH.

v2中的新功能：

CLEARPASS_REDACT_SENSITIVE=true （默认值：true）--响应数据屏蔽
CLEARPASS_TIMEOUT --HTTP超时（秒）

在v2中删除：

CLEARPASS_MAX_PAGES --分页现在由ClearPass通过pyclearpass本地处理

命令/入口点--未更改✅

clearpass-mcp 命令名称和 python -m clearpass_mcp 保持不变。

工具——打破变化⚠️

v1工具	v2等效工具
`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", ...)`

发展

看贡献.md 用于设置、测试和PR指南。

# 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

覆盖范围：pyclearpass与ClearPass API

pyclearpass v1.0.8提供 816次操作 穿过 16个API等级:

类别	类别	操作
身份	身份	71
政策要素	ApiPolicy要素+ApiEnforcementProfile	297
会话控制	ApiSessionControl	16
机载和CA	ApiCertification授权+ApiPlatform证书	48
OnGuard和可见性	ApiEndpointVisibility+ApiInsight	128
访客管理	ApiGuestActions+ApiGuestConfiguration	33
系统和日志	ApiLogs+ApiLocalServer配置+ApiGlobalServer配置+Api操作+Api集成+Api工具和实用程序	223

这是完整的pyclearpass曲面，相当于完整的ClearPass v1 REST API。

致谢

pyclearpass --官方Aruba Python SDK ClearPass现在用作此服务器中的唯一通信层。
阿鲁巴ClearPass REST API指南 --所有端点路径、请求/响应模式的权威来源，以及身份验证流程。
这个 MCP Python SDK --上游 FastMCP 为该服务器的工具和资源注册提供支持的框架。

免责声明

这是一个社区项目不附属于、认可或支持惠普企业（HPE）或Aruba Networks。它是在麻省理工学院“按原样”提供的许可证。在部署到实时环境之前，始终在非生产环境中进行测试 ClearPass集群。