Keycloak MCP

🚀 Octodet Keycloak MCP 服务器

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

🚀 快速开始

Octodet Keycloak MCP 服务器为 Keycloak 管理提供了便捷的途径，通过一系列工具可以轻松管理用户、领域和角色等资源。以下是使用前的安装和配置步骤。

✨ 主要特性

• 用户管理：可在各个领域中创建、删除和列出用户。
• 领域管理：具备全面的领域管理功能。
• 安全集成：使用管理员凭证进行身份验证。
• 易于配置：通过环境变量即可完成简单的设置。
• LLM 集成：可与 Claude、ChatGPT 等支持 MCP 的 AI 助手无缝配合使用。

📦 安装指南

通过 NPM（推荐）

该服务器以 NPM 包的形式提供，可按以下方式安装：

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

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

🔧 配置

环境变量

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

在指定领域中创建具有全面用户属性和可选凭证的新用户。 必需参数：

• 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 与用户名：大多数操作需要用户 ID（UUID），而不是用户名。使用 list-users 查找正确的用户 ID。
2. 客户端标识：clientId 参数接受可读的客户端 ID 和 UUID 标识符。
3. 领域验证：在执行操作前，始终使用 list-realms 验证领域名称。
4. 角色发现：在尝试分配角色之前，使用 list-roles 发现可用的角色。
5. 错误处理：所有工具都提供详细的错误消息，用于排查身份验证、权限或参数问题。

🔧 技术细节

开发

设置开发环境

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

# 安装依赖
npm install

# 以监视模式启动开发服务器
npm run watch

添加新工具

要向服务器添加新工具，请按以下步骤操作：

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

测试

使用 MCP 检查器

MCP 检查器是测试 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 - 为开发者构建智能工具