STARWARCLOUD STARWAR.AI
返回市场
钥匙门-企业管理平台

钥匙门-企业管理平台

作者：Octodet2 星标更新：2025-06-30
安装使用来源：spider==github.com

项目介绍

Octodet Keycloak MCP Server

npm 版本 许可证: MIT

一个强大的用于管理 Keycloak 的 Model Context Protocol 服务器，提供了一整套工具通过 LLM 接口来管理用户、领域、角色和其他 Keycloak 资源。

<a href="https://glama.ai/mcp/servers/@Octodet/keycloak-mcp"> <img width="380" height="200" src="https://gips1.baidu.com/it/u=3537824397,2936753144&fm=3081&app=3081&f=PNG?w=760&h=400" alt="高级 Keycloak 服务器 MCP 服务器" /> </a>

功能

  • 用户管理: 在不同领域创建、删除和列出用户
  • 领域管理: 全面的领域管理能力
  • 安全集成: 使用管理员凭证进行身份验证
  • 简单配置: 通过环境变量进行简单设置
  • LLM 集成: 无缝使用 Claude、ChatGPT 和其他兼容 MCP 的 AI 助手

安装

通过 NPM（推荐）

该服务器作为 NPM 包可用：

# 直接使用 npx
npx -y @octodet/keycloak-mcp

# 或全局安装
npm install -g @octodet/keycloak-mcp

配置

环境变量

变量名称描述默认值
KEYCLOAK_URLKeycloak 服务器 URLhttp://localhost:8080
KEYCLOAK_ADMIN管理员用户名admin
KEYCLOAK_ADMIN_PASSWORD管理员密码admin
KEYCLOAK_REALM默认领域master

MCP 客户端配置

VS Code

在你的 settings.json 中添加以下内容：

{
  "mcp.servers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "@octodet/keycloak-mcp"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

Claude Desktop

在你的 Claude Desktop 配置文件中配置：

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "@octodet/keycloak-mcp"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

本地开发

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

可用工具

该服务器提供了全面的 MCP 工具集，用于 Keycloak 管理。每个工具都设计用于执行跨领域、用户和角色的具体管理任务。

📋 工具概述

工具类别描述
create-user用户管理在指定领域创建新用户
delete-user用户管理从领域中删除现有用户
list-users用户管理列出指定领域的所有用户
list-realms领域管理列出所有可用领域
list-roles角色管理列出特定客户端的所有角色
update-user-roles角色管理为用户添加或移除客户端角色

👥 用户管理

create-user

在指定领域创建具有全面用户属性和可选凭据的新用户。

必需参数：

  • realm (字符串): 目标领域名称
  • username (字符串): 新用户的唯一用户名
  • email (字符串): 有效的电子邮件地址
  • firstName (字符串): 用户名
  • lastName (字符串): 用户姓

可选参数：

  • enabled (布尔值): 启用/禁用用户账户（默认: true）
  • emailVerified (布尔值): 标记电子邮件已验证
  • credentials (数组): 设置密码的凭据对象数组

凭据对象结构：

  • type (字符串): 凭据类型（例如，“password”）
  • value (字符串): 凭据值
  • temporary (布尔值): 是否必须在首次登录时更改密码

示例用法：

{
  "realm": "my-app-realm",
  "username": "john.doe",
  "email": "john.doe@company.com",
  "firstName": "John",
  "lastName": "Doe",
  "enabled": true,
  "emailVerified": true,
  "credentials": [
    {
      "type": "password",
      "value": "TempPassword123!",
      "temporary": true
    }
  ]
}

响应: 返回创建的用户ID和确认消息。

delete-user

永久地从指定领域中删除用户。此操作无法撤销。

必需参数：

  • realm (字符串): 目标领域名称
  • userId (字符串): 要删除用户的唯一标识符

示例用法：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c"
}

响应: 成功删除的确认消息。

⚠️ 警告: 此操作不可逆。确保您有正确的用户ID后再执行。

list-users

检索指定领域中所有用户的列表及其基本信息。

必需参数：

  • realm (字符串): 目标领域名称

示例用法：

{
  "realm": "my-app-realm"
}

响应: 返回显示用户名和用户ID的格式化列表，适用于领域中的所有用户。

🏛️ 领域管理

list-realms

检索 Keycloak 实例中的所有可用领域。

参数: 无需任何参数

示例用法：

{}

响应: 返回 Keycloak 安装中所有领域名称的列表。

使用场景：

  • 发现可用领域
  • 在其他操作前验证领域名称
  • 对 Keycloak 设置的行政概览

🔐 角色管理

list-roles

列出特定客户端在领域内定义的所有角色。有助于在分配之前理解可用权限和角色。

必需参数：

  • realm (字符串): 目标领域名称
  • clientId (字符串): 目标客户端的客户端ID或UUID

示例用法：

{
  "realm": "my-app-realm",
  "clientId": "my-application"
}

使用客户端UUID的替代方法：

{
  "realm": "my-app-realm",
  "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

响应: 返回指定客户端可用的所有角色名称的格式化列表。

💡 提示: 您可以使用客户端的人类可读ID或其UUID标识符。

update-user-roles

管理用户的客户端角色分配。允许在一个操作中添加和移除角色。

必需参数：

  • realm (字符串): 目标领域名称
  • userId (字符串): 用户的唯一标识符
  • clientId (字符串): 客户端ID或UUID

可选参数：

  • rolesToAdd (数组): 要分配给用户的角色名称列表
  • rolesToRemove (数组): 要从用户移除的角色名称列表

示例用法 - 添加角色：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToAdd": ["admin", "user-manager", "report-viewer"]
}

示例用法 - 移除角色：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToRemove": ["temporary-access", "beta-tester"]
}

示例用法 - 组合操作：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToAdd": ["senior-user"],
  "rolesToRemove": ["junior-user", "trainee"]
}

响应: 详细总结添加、移除的角色以及遇到的任何错误。

🔍 注意事项：

  • 必须至少提供 rolesToAdd 或 rolesToRemove
  • 不存在的角色会被跳过并带有警告
  • 操作对每个角色列表是原子性的（每种操作类型要么全部成功，要么全部失败）

🚀 使用提示

  1. 用户ID vs 用户名: 大多数操作需要用户ID（UUID），而不是用户名。使用 list-users 查找正确的用户ID。
  2. 客户端识别: clientId 参数接受人类可读的客户端ID和UUID标识符。
  3. 领域验证: 在执行操作前始终使用 list-realms 验证领域名称。
  4. 角色发现: 使用 list-roles 在尝试角色分配前发现可用角色。
  5. 错误处理: 所有工具都提供详细的错误消息以解决认证、权限或参数问题。

开发

设置开发环境

# 克隆仓库
git clone <repository-url>

# 安装依赖
npm install

# 使用 watch 模式启动开发服务器
npm run watch

添加新工具

要向服务器添加新工具：

  1. 在 src/index.ts 中使用 Zod 定义工具模式
  2. 将工具定义添加到 ListToolsRequestSchema 处理程序
  3. 在 CallToolRequestSchema 切换语句中实现工具处理器
  4. 更新此 README 文档以记录新工具

测试

使用 MCP Inspector

MCP Inspector 是测试您的 MCP 服务器的好工具：

npx -y @modelcontextprotocol/inspector npx -y @octodet/keycloak-mcp

集成测试

与本地 Keycloak 实例一起测试：

# 使用 Docker 启动 Keycloak
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

# 在另一个终端运行 MCP 服务器
npm run build
node build/index.js

部署

NPM 包

该项目发布到 NPM 下的 @octodet/keycloak-mcp。

自动部署

该项目使用 GitHub Actions 进行 CI/CD，在创建新版本时自动测试并发布到 NPM。

前提条件

  • Node.js 18 或更高版本
  • 运行中的 Keycloak 实例

许可证

本项目根据 MIT 许可证授权 - 详情见 LICENSE 文件。

作者

Octodet - 为开发者构建智能工具