AI导哈

Keycloak用户管理协议

AKC-MCP是一个全面的Keycloak身份和访问管理协议服务器，提供高级用户管理功能和内置安全特性。

  • by aelkz
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 aelkz/another-keycloak-mcp

使用说明

AKC-MCP（另一款钥匙斗篷MCP）

Keycloak IAM的综合模型上下文协议（MCP）服务器，具有高级用户管理功能和内置安全功能。

有关安装和设置说明，请参阅 设置.md

概述

AKC-MCP为Keycloak提供了一个完整的MCP接口，使Claude等AI助手能够安全有效地管理身份和访问管理操作。它使用TypeScript和官方Keycloak管理客户端构建，提供 45工具 跨用户管理、组管理、领域操作、身份验证流和客户端范围。

主要特点

  • 🔍 高级用户搜索：多字段搜索，精确/模糊匹配，重复检测，IDP链接检查
  • 👥 集团综合管理：具有属性管理、层次导航和布尔标志的完整CRUD
  • 🌐 领域操作：导出、统计、SAML证书监控、自定义SPI检测
  • 🔐 认证管理：流量检查、所需操作、配置分析
  • 🎯 客户范围管理：OIDC和SAML作用域的完整CRUD操作
  • 🛡️ 安全功能：开发/生产模式、只读模式、操作警告
  • 📝 类型安全：带Zod运行时验证的完整TypeScript
  • 🔌 双重运输：支持Stdio（MCP）和HTTP/SSE

设计用于

  • Keycloak管理员和DevOps团队
  • 身份和访问管理自动化
  • 批量用户操作和审计
  • 领域配置管理
  • 安全合规性监控
  • 开发和测试工作流程

可用工具（共45个）

用户管理（13个工具）

高级用户查找和管理以及安全检查。

工具 说明
搜索用户 多字段搜索（用户名、电子邮件、名字、姓氏），精确/模糊匹配
获取用户详细信息 完整的用户配置文件，包括属性、组和IDP链接
检查多个帐户 查找共享同一电子邮件的多个用户帐户
检查用户idp代理链接 检查用户是否链接到身份提供者（代理链接）
获取用户idp链接 列出用户的所有身份提供程序连接
列出用户属性 获取用户的所有自定义属性
列出用户会话 查看活动用户会话
创建用户 使用可选的临时密码创建新用户
更新用户 修改用户信息
删除用户 删除用户（带有警告的破坏性操作）
重置密码 重置用户密码（临时或永久）
切换用户状态 启用或禁用用户帐户
列出用户 使用分页列出域中的所有用户

集团管理（16种工具）

具有属性支持的完整组生命周期管理。

工具 说明
列出组 列出所有具有可选搜索筛选的组
获取组 获取详细的组信息
创建组 创建新组或子组
更新组 修改组名或属性
删除组 删除组（破坏性操作）
将用户添加到组 将用户添加到组成员资格
从组中删除用户 从组中删除用户
列出用户组 列出用户所属的所有组
列出组成员 列出特定组中的所有用户
按属性搜索组 按属性键值对搜索组
获取组属性 获取组的所有属性
设置组属性 设置或更新组属性
删除组属性 删除组属性
切换组布尔属性 切换布尔属性（真/假标志）
获取父组 向上导航组层次结构
获取子组 使用可选的递归遍历获取子组

领域操作（6个工具）

领域配置、统计和管理。

工具 说明
列出领域 列出所有可用的Keycloak领域
获取领域 获取详细的领域配置
获取领域统计信息 获取统计数据（用户、组、客户端、会话）
出口领域 使用细粒度选项导出领域配置
检查saml证书 监控SAML证书过期
列出领域spis 列出自定义服务提供商接口

身份验证（3个工具）

身份验证流程和所需操作管理。

工具 说明
列出身份验证流程 列出域中的所有身份验证流
获取身份验证流 获取包括执行在内的流程详细信息
列出所需操作 列出所有必需的操作配置

客户范围（7个工具）

OIDC和SAML客户端范围管理。

工具 说明
列出客户端作用域 列出领域中的所有客户端作用域
获取客户端范围 使用协议映射器获取范围详细信息
创建客户端作用域 创建新的OIDC或SAML作用域
更新客户端范围 修改现有客户端范围
删除客户端作用域 删除客户端作用域（破坏性）
分配客户端范围 为客户端分配范围（默认/可选）
删除客户端作用域 从客户端删除范围分配

安全功能

操作模式

发展模式 （默认）

  • 允许写入操作，但有警告
  • 用于调试的完整错误堆栈跟踪
  • 详细日志记录可用

生产模式

OPERATION_MODE=production
  • 写入操作的额外确认
  • 增强了对破坏性操作的警告
  • 山宁泰错误消息

只读模式

READ_ONLY_MODE=true
  • 阻止所有写入操作（创建、更新、删除）
  • 非常适合审计和检查
  • 对生产环境安全
  • 非常适合学习和探索

安全检查

所有写入操作包括：

  • ✅ 操作模式验证
  • ✅ 只读模式强制
  • ✅ 破坏性操作警告
  • ✅ 结构化日志记录
  • ✅ 响应中的安全警告信息

建筑

技术栈

  • 语言：具有严格模式的TypeScript
  • 运行时：Node.js 18+
  • Keycloak客户端：官方 @keycloak/keycloak-admin-client v26.x
  • MCP-SDK: @modelcontextprotocol/sdk
  • 验证：用于运行时类型检查的Zod模式
  • 日志记录：Winston结构化日志
  • 构建：tsup用于高效的ESM捆绑

项目结构

src/
├── common/              # Server setup, constants
├── config/              # Environment-based configuration
├── schemas/             # Zod validation schemas
├── services/            # Keycloak client wrapper
├── tools/               # MCP tool implementations
│   ├── user-tools.ts              (13 tools)
│   ├── group-tools.ts             (16 tools)
│   ├── realm-operations.ts        (3 tools)
│   ├── realm-tools.ts             (3 tools)
│   ├── authentication-tools.ts    (3 tools)
│   └── client-scope-tools.ts      (7 tools)
├── types/               # TypeScript definitions
├── utils/               # Logger, safety checks
└── index.ts             # Main entry point

快速开始

先决条件

  • Node.js 18+
  • Keycloak服务器正在运行（建议使用v26.4.5）
  • Keycloak管理员凭据

安装

npm install -g another-keycloak-mcp

基本配置

# Create .env file
cat > .env << EOF
KEYCLOAK_URL=http://0.0.0.0:8082
KEYCLOAK_REALM=master
KEYCLOAK_ADMIN_USERNAME=admin
KEYCLOAK_ADMIN_PASSWORD=admin
EOF

# Run
akc-mcp

有关完整的设置说明，请参阅 设置.md

用例

用户管理

  • 批量用户创建和更新
  • 重复电子邮件检测和清理
  • 身份提供者链接验证
  • 会话监控和管理
  • 用户属性审核

组管理

  • 动态集团组织
  • 通过布尔属性进行特征标志管理
  • 组层次导航
  • 批量会员操作
  • 基于属性的组过滤

领域操作

  • 配置备份和导出
  • SAML证书过期监控
  • 自定义SPI库存
  • 多领域统计数据收集
  • 领域配置分析

认证

  • 流量配置检查
  • 所需行动管理
  • 身份验证方法审核
  • 登录流分析

客户范围

  • 范围模板管理
  • 批量范围分配
  • OIDC/SAML配置
  • 协议映射器分析

示例用法

搜索用户

{
  "tool": "search-user",
  "arguments": {
    "realm": "master",
    "email": "@example.com",
    "exact": false
  }
}

检查身份提供者链接

{
  "tool": "check-user-idp-broker-link",
  "arguments": {
    "realm": "master",
    "userId": "user-id-here",
    "identityProvider": "google"
  }
}

按属性搜索组

{
  "tool": "search-groups-by-attributes",
  "arguments": {
    "realm": "master",
    "attributeKey": "feature_flag",
    "attributeValue": "true",
    "exact": true
  }
}

导出领域配置

{
  "tool": "export-realm",
  "arguments": {
    "realm": "master",
    "includeUsers": false,
    "includeGroups": true,
    "includeRoles": true,
    "includeClients": true
  }
}

监控SAML证书

{
  "tool": "check-saml-certificates",
  "arguments": {
    "realm": "production",
    "warnDays": 30
  }
}

文档

版本兼容性

  • 钥匙斗篷：使用版本26.4.5进行测试
  • Node.js：需要版本18或更高版本
  • MCP协议：版本1.0

备注：虽然此服务器是为Keycloak 26.4.5设计的，但它可能适用于其他版本。某些功能可能会因版本不匹配而表现不同。

许可证

MIT许可证-请参阅 许可证 详细信息文件

致谢

相关 MCP