Advanced Keycloak Mcp Server

Octodet Keycloak MCP 服务

功能强大的 Keycloak 管理 Model Context Protocol 服务，可通过大模型接口提供全面的工具集，用于管理用户、realm、角色及其他 Keycloak 资源。

功能

• 用户管理：跨 realm 创建、删除和列出用户
• Realm 管理：全面的 realm 管理功能
• 安全集成：使用管理员凭据进行身份验证
• 轻松配置：通过环境变量简单设置
• 大模型集成：与 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	Keycloak 服务 URL	http://localhost:8080
KEYCLOAK_ADMIN	管理员用户名	admin
KEYCLOAK_ADMIN_PASSWORD	管理员密码	admin
KEYCLOAK_REALM	默认 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。每个工具都针对跨 realm、用户和角色执行特定管理任务而设计。

📋 工具概览

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

---

👥 用户管理

create-user

在指定 realm 中创建新用户，并设置全面的用户属性和可选凭据。

必需参数：

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

可选参数：

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

凭据对象结构：

• type（字符串）：凭据类型（例如，“password”）
• value（字符串）：凭据值
• temporary（布尔值）：是否要求用户首次登录时更改密码

用法示例：

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

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

---

delete-user

从指定的 realm 中永久删除用户。此操作无法撤销。

必填参数：

• realm（string）：目标 realm 名称
• userId（string）：要删除用户的唯一标识符

使用示例：

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

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

**⚠️ 警告：**此操作不可逆。执行前请确保用户 ID 正确。

---

list-users

获取指定 realm 中所有用户的列表及其基本信息。

必填参数：

• realm（string）：目标 realm 名称

使用示例：

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

**响应：**返回格式化列表，显示 realm 中所有用户的用户名和用户 ID。

---

🏛️ Realm 管理

list-realms

获取 Keycloak 实例中所有可用的 realm。

**参数：**无需参数

使用示例：

{}

**响应：**返回 Keycloak 安装中所有可用的 realm 名称。

使用场景：

• 查找可用的 realm
• 在执行其他操作前验证 realm 名称
• 概览 Keycloak 设置

---

🔐 角色管理

list-roles

列出 realm 中特定客户端定义的所有角色。在分配角色前，可用于了解可用的权限和角色。

必填参数：

• realm（string）：目标 realm 名称
• 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）：目标 realm 名称
• 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. 客户端标识：clientId 参数接受易读的客户端 ID 和 UUID 标识符。

3. Realm 验证：执行操作前，请务必使用 list-realms 验证 realm 名称。

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. 使用 Zod 在 src/index.ts 中定义工具架构
2. 将工具定义添加到 ListToolsRequestSchema 处理程序
3. 在 CallToolRequestSchema switch 语句中实现工具处理程序
4. 更新此 README，记录新工具

测试

使用 MCP Inspector

MCP Inspector 是测试 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 包

此项目以 @octodet/keycloak-mcp 的名称发布到 NPM。

自动化部署

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

前提条件

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

许可证

本项目基于 MIT 许可证授权，详情请参阅 LICENSE 文件。

作者

Octodet - 为开发者打造智能工具