AI导哈

Keycloak管理服务器

一个强大的Keycloak管理服务器，提供通过LLM接口管理用户、领域、角色等Keycloak资源的全面工具集。

  • by Octodet
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 octodet/keycloak-mcp

使用说明

Octodet Keycloak MCP服务器

用于Keycloak管理的强大模型上下文协议服务器，提供了一套全面的工具，通过LLM接口管理用户、领域、角色和其他Keycloak资源。

特性

  • 用户管理：跨领域创建、删除和列出用户
  • 领域管理：全面的领域管理功能
  • 安全集成：使用管理员凭据进行身份验证
  • 易于配置：使用环境变量进行简单设置
  • LLM集成：与Claude、ChatGPT和其他MCP兼容的AI助手无缝使用

安装

通过NPM（推荐）

服务器可作为NPM包使用：

# Direct usage with npx
npx -y @octodet/keycloak-mcp

# Or global installation
npm install -g @octodet/keycloak-mcp

配置

环境变量

变量 描述 默认值
KEYCLOAK_URL 密钥斗篷服务器URL http://localhost:8080
keycloak管理员 管理员用户名 管理员
KEYCLOAK_ADMIN_PASSWORD 管理员密码 管理员
KEYCLOAK_REALM 默认领域 主

MCP客户端配置

VS代码

将此添加到您的 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配置文件中配置：

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

可用工具

服务器为Keycloak管理提供了一套全面的MCP工具。每个工具都旨在跨领域、用户和角色执行特定的管理任务。

📋 工具概述

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

👥 用户管理

create-user

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

所需参数：

  • realm （string）：目标领域名称
  • username （string）：新用户的唯一用户名
  • email （string）：有效的电子邮件地址
  • firstName （string）：用户的名字
  • lastName （string）：用户的姓氏

可选参数：

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

凭证对象结构：

  • type （string）：凭证类型（例如“密码”）
  • value （string）：凭证值
  • temporary （boolean）：首次登录时是否必须更改密码

示例用法：

{
  "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 （string）：目标领域名称
  • userId （string）：要删除的用户的唯一标识符

示例用法：

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

答复： 删除成功的确认消息。

⚠️ 警告： 此操作是不可逆的。在执行之前，请确保您拥有正确的用户ID。

list-users

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

所需参数：

  • realm （string）：目标领域名称

示例用法：

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

答复： 返回一个格式化的列表，显示领域中所有用户的用户名和用户ID。

🏛️ 领域管理

list-realms

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

参数： 无需

示例用法：

{}

答复： 返回Keycloak安装中所有可用域名的列表。

使用案例：

  • 发现可用领域
  • 在其他操作之前验证域名
  • Keycloak设置的管理概述

🔐 角色管理

list-roles

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

所需参数：

  • realm （string）：目标领域名称
  • clientId （string）：目标客户端的客户端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 （string）：目标领域名称
  • userId （string）：用户的唯一标识符
  • clientId （string）：客户端ID或UUID

可选参数：

  • rolesToAdd （array）：要分配给用户的角色名称列表
  • rolesToRemove （array）：要从用户中删除的角色名称列表

示例用法-添加角色：

{
  "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与用户名：大多数操作需要用户ID（UUID），而不是用户名。使用 list-users 以找到正确的用户ID。

  2. 客户端标识：The clientId 参数接受人类可读的客户端ID和UUID标识符。

  3. 领域验证：始终使用验证域名 list-realms 在执行操作之前。

  4. 角色发现：使用 list-roles 在尝试角色分配之前发现可用角色。

  5. 错误处理：所有工具都提供详细的错误消息，用于排除身份验证、权限或参数问题。

发展

设置您的开发环境

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Start the development server with watch mode
npm run watch

添加新工具

要向服务器添加新工具，请执行以下操作：

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

测试

使用MCP检查器

MCP检查器是测试MCP服务器的好工具：

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

集成测试

对于使用本地Keycloak实例进行测试：

# Start Keycloak with Docker
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

# In another terminal, run the MCP server
npm run build
node build/index.js

部署

NPM包

该项目已发布给NPM @octodet/keycloak mcp.

自动化部署

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

先决条件

  • Node.js 18或更高版本
  • 正在运行Keycloak实例

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

作者

Octodet-为开发人员构建智能工具

相关 MCP