Keycloak MCP Server

这是一个用于 Keycloak 的模型上下文协议（MCP）服务器实现，提供了一个标准化接口来管理 Keycloak 用户和领域。

描述

该项目实现了一个与 Keycloak 集成的 MCP 服务器，允许您通过一个标准化协议来管理 Keycloak 用户和领域。它使用官方的 Keycloak 管理客户端与 Keycloak 的 API 进行交互。

功能演示

https://github.com/user-attachments/assets/4b02a049-b8d6-4cc5-a7b4-564a0e758dd8

可用工具

创建用户

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

输入参数：

• realm: 领域名
• username: 新用户的用户名
• email: 用户的电子邮件地址
• firstName: 用户的名字
• lastName: 用户的姓氏

删除用户

从指定的领域中删除一个用户。

输入参数：

• realm: 领域名
• userId: 要删除的用户的ID

列出所有领域

列出所有可用的领域。

列出所有用户

列出指定领域的所有用户。

输入参数：

• realm: 领域名

列出所有客户端

列出指定领域的所有客户端。

输入参数：

• realm: 领域名

列出所有组

列出指定领域的所有组。

输入参数：

• realm: 领域名

列出特定客户端的角色

列出特定客户端在领域中的所有角色。

输入参数：

• realm: 领域名
• clientUniqueId: 客户端的唯一ID

将客户端角色分配给用户

将客户端角色分配给特定用户。

输入参数：

• realm: 领域名
• userId: 用户的ID
• clientUniqueId: 客户端的唯一ID
• roleName: 要分配的角色名称

将用户添加到组

将用户添加到特定组。

输入参数：

• realm: 领域名
• userId: 用户的ID
• groupId: 组的ID

先决条件

• Node.js（推荐最新长期支持版本）
• npm
• 正在运行的 Keycloak 实例

安装

通过 Smithery 安装

要通过 Smithery 自动安装 keycloak-mcp 到 Claude Desktop：

$ npx -y @smithery/cli install @HaithamOumerzoug/keycloak-mcp --client claude

通过 NPM 安装

配置环境：

• 您可以使用命令行参数或环境变量设置配置选项：
  • --keycloak-url <Keycloak 实例 URL>
  • --keycloak-admin <管理员用户名>
  • --keycloak-admin-password <管理员密码>
• 如果同时设置了这些参数，它们会覆盖环境变量。

启动服务器：

该服务器作为 NPM 包提供：

# 直接使用 npx
$ npx -y keycloak-mcp --keycloak-url <Keycloak 实例 URL> --keycloak-admin <管理员用户名> --keycloak-admin-password <管理员密码>

# 或全局安装
$ npm install -g keycloak-mcp@latest
$ keycloak-mcp --keycloak-url <Keycloak 实例 URL> --keycloak-admin <管理员用户名> --keycloak-admin-password <管理员密码>

配置

使用 NPM 包

在您的 Cursor IDE、Cline 或 Claude Desktop MCP 配置文件中配置服务器：

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

本地开发

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

开发

要设置开发环境：

1. 克隆仓库
2. 安装依赖项：

   npm install
   

3. 设置环境变量

   cp .env.template .env
   # 编辑 .env 文件并设置所有变量的适当值
   

4. 启动项目：

   npm run dev
   

可用脚本

• npm run build - 构建项目并生成 CLI 可执行文件
• npm run prepare - 运行构建脚本（在包安装期间使用）
• npm run dev - 监视更改并自动重新构建
• npm start - 启动服务器（用于生产）

依赖项

主要依赖项

• @keycloak/keycloak-admin-client - 官方 Keycloak 管理客户端
• @modelcontextprotocol/sdk - MCP SDK 用于标准化协议实现
• zod - TypeScript 优先的模式验证
• chalk - 终端字符串样式化
• yargs - 解析命令行参数

开发依赖项

• typescript - 支持 TypeScript
• @types/node - TypeScript 对于 Node.js 的定义
• shx - 跨平台的 shell 命令
• ts-node - TypeScript 执行和 Node.js 的 REPL
• rimraf - 一个跨平台的删除目录工具
• @types/yargs - TypeScript 对于 yargs 的定义

许可证

MIT

作者

OUMERZOUG Haitham