使用说明

Keycloak模型上下文协议服务器

用于Keycloak管理的综合模型上下文协议（MCP）服务器，提供 80+工具 直接从Claude Desktop或Cursor AI等AI助手管理用户、领域、客户端、角色、组、会话、事件、组织、协议映射器、用户属性、客户端范围和身份提供者。

🚀 特性

👤 用户管理

✅ 创建、更新和删除用户
✅ 列出、搜索和获取用户详细信息
✅ 重置用户密码
✅ 注销用户会话
✅ 管理用户角色和组
✅ 新用户属性管理（对组织数据至关重要）

🏛️ 领域管理

✅ 列出、创建、更新和删除领域
✅ 获取详细的领域设置和配置
✅ 管理领域级安全策略

🔧 客户管理

✅ 注册、更新和删除客户端/应用程序
✅ 列出域中的所有客户端
✅ 配置客户端设置和重定向URI
✅ 新协议映射器管理（对JWT声明至关重要）

🎭 角色管理

✅ 创建、更新和删除角色（领域和客户端级别）
✅ 从用户和组中分配和删除角色
✅ 列出所有角色和用户角色分配
✅ 新复合角色和角色层次结构
✅ 新按ID进行高级角色操作
✅ 新查找具有特定角色的用户

👥 组管理

✅ 创建、更新和删除用户组
✅ 在组中添加和删除用户
✅ 管理分层组结构
✅ 新组属性管理
✅ 新儿童组和子组管理
✅ 新集团成员列表和管理

🏢 组织管理 ⭐ 新

✅ 创建、更新和删除组织
✅ 添加和删除组织成员
✅ 列出组织和成员
✅ 组织属性管理

🔗 身份提供者管理 ⭐ 新

✅ 创建、更新和删除身份提供程序（SSO）
✅ 身份提供程序映射器管理
✅ SAML和OIDC提供者配置
✅ 外部用户属性映射

🎯 客户范围管理 ⭐ 新

✅ 创建、更新和删除客户端作用域
✅ 客户端作用域的协议映射器
✅ 令牌范围管理

📊 会议和活动管理

✅ 列出活动用户会话
✅ 监控身份验证和管理事件
✅ 清除事件日志并管理会话生命周期

🛡️ 高级功能

✅ 防弹认证 使用新的客户端实例
✅ 全面的错误处理 详细记录
✅ 与跨平台支持 （Windows、macOS、Linux）
✅ 生产准备就绪 使用TypeScript和健壮的架构
✅ 组织JWT索赔 -解决代币中的组织可见性问题
✅ 80+工具 -完整的Keycloak管理覆盖

📋 先决条件

Node.js 18或更高版本
正在运行Keycloak实例 （本地或远程）
Keycloak管理员凭据 具有适当的权限
AI助手 支持MCP（克劳德桌面、光标AI等）

📦 安装

全局安装（推荐）

npm install -g keycloak-mcp-server

使用NPX（无需安装）

npx keycloak-mcp-server

本地项目安装

npm install keycloak-mcp-server

地方发展

git clone https://github.com/M0-AR/keycloak-mcp-server.git
cd keycloak-mcp-server
npm install
npm run build

⚙️ 配置

适用于Cursor AI

添加到Cursor MCP配置文件(~/.cursor/mcp.json):

选项1：使用NPX（推荐）

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["keycloak-mcp-server"],
      "env": {
        "KEYCLOAK_URL": "https://your-keycloak-instance.com",
        "KEYCLOAK_ADMIN": "your-admin-username",
        "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}

选项2：如果全局安装

{
  "mcpServers": {
    "keycloak": {
      "command": "keycloak-mcp-server",
      "env": {
        "KEYCLOAK_URL": "https://your-keycloak-instance.com", 
        "KEYCLOAK_ADMIN": "your-admin-username",
        "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}

适用于克劳德桌面

添加到您的Claude Desktop配置中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["keycloak-mcp-server"],
      "env": {
        "KEYCLOAK_URL": "https://your-keycloak-instance.com",
        "KEYCLOAK_ADMIN": "your-admin-username",
        "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}

🌍 环境变量

变量	描述	默认值	必填
`KEYCLOAK_URL`	Keycloak实例的基本URL	`http://localhost:8080`	✅
`KEYCLOAK_ADMIN`	管理员用户名	`admin`	✅
`KEYCLOAK_ADMIN_PASSWORD`	管理员密码	`admin`	✅

��️ 可用工具（80+工具）

👤 用户管理工具

`create-user`

在指定领域中创建新用户。

Create a user in "master" realm: username "john.doe", email "john@example.com", first name "John", last name "Doe"

`update-user`

更新用户信息（电子邮件、姓名、启用状态）。

Update user "user-id-123" in "master" realm to change email to "newemail@example.com"

`delete-user`

从域中删除用户。

Delete user with ID "user-id-123" from "master" realm

`list-users`

列出域中的所有用户。

List all users in the "master" realm

`search-users`

使用筛选器（用户名、电子邮件、名字、姓氏）搜索用户。

Search for users with email containing "wateen.io" in "master" realm, limit 10 results

`get-user`

获取特定用户的详细信息。

Get details for user ID "user-id-123" in "master" realm

`reset-user-password`

重置用户密码。

Reset password for user "user-id-123" in "master" realm to "newPassword123", make it temporary

`logout-user`

注销特定用户的所有会话。

Logout all sessions for user "user-id-123" in "master" realm

`set-user-attributes` ⭐ 新

设置用户属性（对组织数据存储至关重要）。

Set organization attribute for user "user-id-123" in "master" realm: {"organization": ["wateen-corp"]}

`get-user-attributes` ⭐ 新

获取用户属性，包括非托管属性。

Get all attributes for user "user-id-123" in "master" realm

🏛️ 领域管理工具

`list-realms`

列出所有可用领域。

Show me all available realms in Keycloak

`create-realm`

创建具有可配置设置的新领域。

Create a new realm called "company" with display name "Company Realm", enabled

`update-realm`

更新领域设置和配置。

Update realm "company" to change display name to "Updated Company"

`delete-realm`

删除现有领域。

Delete the realm "test-realm"

`get-realm-settings`

检索领域的详细设置。

Get detailed settings for the "master" realm

🔧 客户端管理工具

`create-client`

在域中注册新的客户端/应用程序。

Create client "my-app" in "master" realm with redirect URIs ["http://localhost:3000/*"]

`update-client`

更新客户端设置（重定向URI、协议映射器等）。

Update client "my-app" in "master" realm to add new redirect URI "https://app.example.com/*"

`delete-client`

从域中删除客户端。

Delete client "old-app" from "master" realm

`list-clients`

列出一个领域中的所有客户端。

List all clients in the "master" realm

`create-protocol-mapper` ⭐ 新

为客户创建协议映射器（对于JWT组织的声明至关重要）。

Create organization group mapper for client "my-app" in "master" realm to include "organization" claim in JWT

`update-protocol-mapper` ⭐ 新

更新现有的协议映射器。

Update protocol mapper "mapper-id-123" for client "my-app" in "master" realm

`delete-protocol-mapper` ⭐ 新

从客户端删除协议映射器。

Delete protocol mapper "mapper-id-123" from client "my-app" in "master" realm

`list-protocol-mappers` ⭐ 新

列出客户端的所有协议映射器。

List all protocol mappers for client "my-app" in "master" realm

🎯 客户范围管理工具⭐ 新

`create-client-scope`

创建一个新的客户端作用域来管理令牌作用域。

Create client scope "organization-scope" in "master" realm for organization claims

`update-client-scope`

更新现有客户端范围。

Update client scope "scope-id-123" in "master" realm to change description

`delete-client-scope`

删除客户端作用域。

Delete client scope "scope-id-123" from "master" realm

`list-client-scopes`

列出一个领域中的所有客户端作用域。

List all client scopes in the "master" realm

`get-client-scope`

获取特定客户端范围的详细信息。

Get details for client scope "scope-id-123" in "master" realm

`create-client-scope-protocol-mapper` ⭐ 新

为客户端作用域创建协议映射器。

Create organization mapper for client scope "organization-scope" in "master" realm

`update-client-scope-protocol-mapper` ⭐ 新

更新客户端作用域中的协议映射器。

Update protocol mapper "mapper-id-123" in client scope "scope-id-456" in "master" realm

`delete-client-scope-protocol-mapper` ⭐ 新

从客户端作用域中删除协议映射器。

Delete protocol mapper "mapper-id-123" from client scope "scope-id-456" in "master" realm

`list-client-scope-protocol-mappers` ⭐ 新

列出客户端作用域的协议映射器。

List all protocol mappers for client scope "scope-id-123" in "master" realm

🏢 组织管理工具⭐ 新

`create-organization`

创建一个新组织。

Create organization "wateen-corp" with description "Wateen Corporation" in "master" realm

`update-organization`

更新现有组织。

Update organization "org-id-123" in "master" realm to change name to "Updated Corp"

`delete-organization`

删除组织。

Delete organization "org-id-123" from "master" realm

`list-organizations`

列出一个领域中的所有组织。

List all organizations in "master" realm with search "wateen", limit 10

`get-organization`

获取特定组织的详细信息。

Get details for organization "org-id-123" in "master" realm

`add-organization-member`

将用户添加到组织。

Add user "user-id-123" to organization "org-id-456" in "master" realm

`remove-organization-member`

从组织中删除用户。

Remove user "user-id-123" from organization "org-id-456" in "master" realm

`list-organization-members`

列出一个组织的所有成员。

List all members of organization "org-id-123" in "master" realm, limit 20

🎭 角色管理工具

`create-role`

在领域或客户端级别创建角色。

Create a realm role "manager" with description "Manager role" in "master" realm

`update-role`

修改角色属性。

Update role "manager" in "master" realm to change description to "Updated manager role"

`delete-role`

删除角色。

Delete role "old-role" from "master" realm

`list-roles`

列出一个领域中的所有角色。

List all roles in the "master" realm

`assign-role-to-user`

为用户分配角色。

Assign role "manager" to user "user-id-123" in "master" realm

`remove-role-from-user`

从用户中删除角色。

Remove role "manager" from user "user-id-123" in "master" realm

`get-user-roles`

获取分配给用户的所有角色。

Get all roles for user "user-id-123" in "master" realm

`create-composite-role` ⭐ 新

创建复合角色（角色层次结构）。

Create composite role from "parent-role-id" with child roles ["child-role-1", "child-role-2"] in "master" realm

`get-composite-roles` ⭐ 新

获取角色的复合角色。

Get composite roles for role "role-id-123" in "master" realm, limit 10

`delete-composite-roles` ⭐ 新

从角色中删除复合角色。

Remove composite roles ["child-role-1", "child-role-2"] from role "parent-role-id" in "master" realm

`get-role-by-id` ⭐ 新

按ID获取角色详细信息。

Get role details for role ID "role-id-123" in "master" realm

`update-role-by-id` ⭐ 新

按ID更新角色。

Update role "role-id-123" in "master" realm to change name to "new-role-name"

`delete-role-by-id` ⭐ 新

按ID删除角色。

Delete role with ID "role-id-123" from "master" realm

`find-users-with-role` ⭐ 新

查找具有特定角色的用户。

Find all users with role "manager" in "master" realm, limit 20

`assign-role-to-group` ⭐ 新

为组分配角色。

Assign role "developer" to group "group-id-123" in "master" realm

`remove-role-from-group` ⭐ 新

从组中删除角色。

Remove role "developer" from group "group-id-123" in "master" realm

`get-group-roles` ⭐ 新

获取分配给组的角色。

Get all roles for group "group-id-123" in "master" realm

`list-available-group-roles` ⭐ 新

列出组的可用角色。

List available roles for group "group-id-123" in "master" realm

`list-composite-group-roles` ⭐ 新

列出组的复合角色。

List composite roles for group "group-id-123" in "master" realm

👥 组管理工具

`create-group`

创建用户组。

Create a group called "developers" in "master" realm

`update-group`

更新组属性。

Update group "group-id-123" in "master" realm to change name to "senior-developers"

`delete-group`

删除组。

Delete group "group-id-123" from "master" realm

`list-groups`

列出一个领域中的所有组。

List all groups in the "master" realm

`manage-user-groups`

在组中添加或删除用户。

Add user "user-id-123" to group "group-id-456" in "master" realm

`set-group-attributes` ⭐ 新

设置组属性（组织元数据）。

Set organization attributes for group "group-id-123" in "master" realm: {"department": ["engineering"]}

`get-group-attributes` ⭐ 新

获取组属性。

Get all attributes for group "group-id-123" in "master" realm

`create-child-group` ⭐ 新

创建子组（子组）。

Create child group "junior-devs" under parent group "group-id-123" in "master" realm

`list-sub-groups` ⭐ 新

列出父组的子组。

List subgroups of parent group "group-id-123" in "master" realm, limit 10

`list-group-members` ⭐ 新

列出组的成员。

List all members of group "group-id-123" in "master" realm, limit 20

🔗 身份提供者管理工具⭐ 新

`create-identity-provider`

为SSO集成创建新的身份提供程序。

Create SAML identity provider "company-saml" in "master" realm with SSO URL and certificate

`update-identity-provider`

更新现有的身份提供程序。

Update identity provider "company-saml" in "master" realm to change display name

`delete-identity-provider`

删除身份提供程序。

Delete identity provider "old-saml" from "master" realm

`list-identity-providers`

列出一个领域中的所有身份提供程序。

List all identity providers in "master" realm

`get-identity-provider`

获取特定身份提供者的详细信息。

Get details for identity provider "company-saml" in "master" realm

`create-identity-provider-mapper`

为身份提供程序创建映射器（外部用户映射）。

Create user attribute mapper for identity provider "company-saml" in "master" realm

`update-identity-provider-mapper`

更新身份提供程序映射程序。

Update mapper "mapper-id-123" for identity provider "company-saml" in "master" realm

📊 会话和事件管理工具

`list-sessions`

列出一个领域中的所有活动会话。

List all active sessions in "master" realm

`get-user-sessions`

列出特定用户的活动会话。

Get active sessions for user "user-id-123" in "master" realm

`list-events`

检索身份验证和管理事件。

List last 10 events in "master" realm

`clear-events`

清除事件日志。

Clear all events in "master" realm

🧪 测试与开发

MCP检验员测试

npx @modelcontextprotocol/inspector npx keycloak-mcp-server

访问 http://localhost:6274 交互式测试所有80多种工具。

地方发展

npm run watch    # Auto-rebuild on changes
npm run dev     # Test server directly

压力测试

该服务器已经过80多次连续操作的压力测试，没有身份验证失败，证明了生产级的可靠性。

🔧 建筑

防弹认证系统

新客户端实例：为每个请求创建新的KcAdminClient
重试逻辑：指数回退，最多可尝试2次
连接管理：15秒超时，并进行适当的清理
错误处理：所有场景的全面错误消息

TypeScript实现

类型安全：具有适当接口的完整TypeScript覆盖率
错误处理：详细的错误消息和日志记录
模块化设计：明确区分关注点

📈 生产就绪

该软件包经过了广泛的测试和验证：

✅ 80+连续操作 没有身份验证失败
✅ 跨领域操作 无缝工作
✅ 并行工具执行 支持
✅ 复杂的搜索查询 具有多个过滤器
✅ 错误恢复 以及详细的日志记录
✅ TypeScript编译 零误差
✅ 完整的Keycapture API覆盖范围 与组织管理

🎯 智威汤逊组织问题已解决

此包专门解决了常见的JWT组织问题：

✅ 用户属性：将组织数据存储在用户属性中
✅ 协议映射器：创建映射器以将组织包含在JWT令牌中
✅ 客户范围：管理组织声明的令牌范围
✅ 组织：完整的组织生命周期管理
✅ 组属性：将组织元数据存储在组中

工作流程示例：

使用创建组织 create-organization
使用设置用户组织属性 set-user-attributes
使用创建协议映射器 create-protocol-mapper 将组织纳入JWT
使用将用户添加到组织 add-organization-member

🔒 安全最佳实践

使用环境变量作为凭据
为生产Keycloak实例启用HTTPS
使用强管理员密码
定期轮换凭证
监控管理员事件和会话

🤝 贡献

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
提交更改： git commit -m 'Add amazing feature'
推送到分支： git push origin feature/amazing-feature
打开拉取请求

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

🆘 支持

GitHub问题: 创建问题
文档：查看此README以获取全面的示例
MCP文件: 模型上下文协议

🔗 相关项目

克劳德桌面 -支持MCP的AI助手
光标AI -支持MCP的AI驱动代码编辑器
模型上下文协议 -协议规范
钥匙斗篷 -开源身份和访问管理

📊 包统计信息

80+工具：完成Keycloak管理覆盖
生产就绪：经过广泛测试和验证
TypeScript：全型安全和现代开发经验
交叉平台的：Windows、macOS和Linux支持
零依赖问题：强大的依赖关系管理
组织管理：解决智威汤逊组织可见性问题
高级功能：协议映射器、客户端作用域、身份提供者

由以下材料制成❤️ Keycloak和AI社区

使用说明

Keycloak模型上下文协议服务器

🚀 特性

👤 用户管理

🏛️ 领域管理

🔧 客户管理

🎭 角色管理

👥 组管理

🏢 组织管理 ⭐ 新

🔗 身份提供者管理 ⭐ 新

🎯 客户范围管理 ⭐ 新

📊 会议和活动管理

🛡️ 高级功能

📋 先决条件

📦 安装

全局安装（推荐）

使用NPX（无需安装）

本地项目安装

地方发展

⚙️ 配置

适用于Cursor AI

选项1：使用NPX（推荐）

选项2：如果全局安装

适用于克劳德桌面

🌍 环境变量

��️ 可用工具（80+工具）

👤 用户管理工具

create-user

update-user

delete-user

list-users

search-users

get-user

reset-user-password

logout-user

set-user-attributes ⭐ 新

get-user-attributes ⭐ 新

🏛️ 领域管理工具

list-realms

create-realm

update-realm

delete-realm

get-realm-settings

🔧 客户端管理工具

create-client

update-client

delete-client

list-clients

create-protocol-mapper ⭐ 新

update-protocol-mapper ⭐ 新

delete-protocol-mapper ⭐ 新

list-protocol-mappers ⭐ 新

🎯 客户范围管理工具⭐ 新

create-client-scope

update-client-scope

delete-client-scope

list-client-scopes

get-client-scope

create-client-scope-protocol-mapper ⭐ 新

update-client-scope-protocol-mapper ⭐ 新

delete-client-scope-protocol-mapper ⭐ 新

list-client-scope-protocol-mappers ⭐ 新

🏢 组织管理工具⭐ 新

create-organization

update-organization

delete-organization

list-organizations

get-organization

add-organization-member

remove-organization-member

list-organization-members

🎭 角色管理工具

create-role

update-role

delete-role

list-roles

assign-role-to-user

remove-role-from-user

get-user-roles

create-composite-role ⭐ 新

`create-user`

`update-user`

`delete-user`

`list-users`

`search-users`

`get-user`

`reset-user-password`

`logout-user`

`set-user-attributes` ⭐ 新

`get-user-attributes` ⭐ 新

`list-realms`

`create-realm`

`update-realm`

`delete-realm`

`get-realm-settings`

`create-client`

`update-client`

`delete-client`

`list-clients`

`create-protocol-mapper` ⭐ 新

`update-protocol-mapper` ⭐ 新

`delete-protocol-mapper` ⭐ 新

`list-protocol-mappers` ⭐ 新

`create-client-scope`

`update-client-scope`

`delete-client-scope`

`list-client-scopes`

`get-client-scope`

`create-client-scope-protocol-mapper` ⭐ 新

`update-client-scope-protocol-mapper` ⭐ 新

`delete-client-scope-protocol-mapper` ⭐ 新

`list-client-scope-protocol-mappers` ⭐ 新

`create-organization`

`update-organization`

`delete-organization`

`list-organizations`

`get-organization`

`add-organization-member`

`remove-organization-member`

`list-organization-members`

`create-role`

`update-role`

`delete-role`

`list-roles`

`assign-role-to-user`

`remove-role-from-user`

`get-user-roles`

`create-composite-role` ⭐ 新

`get-composite-roles` ⭐ 新

`delete-composite-roles` ⭐ 新

`get-role-by-id` ⭐ 新

`update-role-by-id` ⭐ 新

`delete-role-by-id` ⭐ 新

`find-users-with-role` ⭐ 新

`assign-role-to-group` ⭐ 新

`remove-role-from-group` ⭐ 新

`get-group-roles` ⭐ 新

`list-available-group-roles` ⭐ 新

`list-composite-group-roles` ⭐ 新

`create-group`

`update-group`

`delete-group`

`list-groups`

`manage-user-groups`

`set-group-attributes` ⭐ 新

`get-group-attributes` ⭐ 新

`create-child-group` ⭐ 新

`list-sub-groups` ⭐ 新

`list-group-members` ⭐ 新

`create-identity-provider`

`update-identity-provider`

`delete-identity-provider`

`list-identity-providers`

`get-identity-provider`

`create-identity-provider-mapper`

`update-identity-provider-mapper`

`list-sessions`

`get-user-sessions`

`list-events`

`clear-events`