使用说明

项目简介

Keycloak MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型 (LLM) 客户端提供与 Keycloak 身份和访问管理系统集成的能力。通过此服务器，LLM 可以调用工具来管理 Keycloak 中的用户和域，例如创建用户、删除用户、列出域和列出用户。

主要功能点

用户管理: 创建和删除 Keycloak 域中的用户。
域管理: 列出 Keycloak 服务器上可用的域。
信息查询: 列出特定域中的用户。
标准化接口: 通过 MCP 协议以标准化的 JSON-RPC 接口与 LLM 客户端通信。

安装步骤

安装 Node.js: 确保你的系统已安装 Node.js 18 或更高版本。

安装 NPM 包: 可以通过 NPM 直接安装和运行 Keycloak MCP Server。打开终端并执行以下命令：

npx -y keycloak-model-context-protocol

或者，你也可以全局安装：

npm install -g keycloak-model-context-protocol

配置 Keycloak 连接: 在运行服务器之前，你需要配置 Keycloak 服务器的连接信息，包括 Keycloak 服务器的 URL、管理员用户名和密码。这些信息通过环境变量传递。

服务器配置

为了让 MCP 客户端（例如 Claude Desktop）连接到 Keycloak MCP Server，你需要配置客户端的 MCP 服务器设置。以下是一个配置示例，你需要将其添加到你的 MCP 客户端的配置文件中（通常是 JSON 格式）。

{
  "mcpServers": {
    "keycloakAdmin": {  // 服务器名称，可以自定义
      "command": "npx",  // 启动服务器的命令，这里使用 npx 直接运行 npm 包
      "args": ["-y", "keycloak-model-context-protocol"], // 命令参数，指定要运行的 npm 包
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",  // Keycloak 服务器的 URL，请替换为你的 Keycloak 服务器地址
        "KEYCLOAK_ADMIN": "admin", // Keycloak 管理员用户名，请替换为你的管理员用户名
        "KEYCLOAK_ADMIN_PASSWORD": "admin" // Keycloak 管理员密码，请替换为你的管理员密码
      }
    }
  }
}

配置参数说明:

'server name': 'keycloakAdmin' (示例名称，可自定义，用于在客户端中引用此服务器)
'command': 'npx' (使用 npx 运行 npm 包)
'args': '["-y", "keycloak-model-context-protocol"]' (指定要运行的 npm 包名)
'env': 环境变量配置，用于连接 Keycloak 服务器:
- 'KEYCLOAK_URL': Keycloak 服务器的访问地址 (例如: 'http://localhost:8080')
- 'KEYCLOAK_ADMIN': Keycloak 管理员用户名 (例如: 'admin')
- 'KEYCLOAK_ADMIN_PASSWORD': Keycloak 管理员密码 (例如: 'admin')

注意: 请确保你的 Keycloak 服务器已启动并运行，并且配置的管理员账号具有足够的权限来管理用户和域。

基本使用方法

启动 MCP 服务器: 配置好 MCP 客户端后，客户端通常会自动启动配置的 MCP 服务器。如果需要手动启动，可以直接在终端运行 'npx -y keycloak-model-context-protocol' 或全局安装后运行 'keycloak-model-context-protocol'。
在 LLM 客户端中使用工具: 在支持 MCP 协议的 LLM 客户端中（例如 Claude Desktop），你可以通过自然语言指令调用 Keycloak MCP Server 提供的工具。例如：
- 让 LLM "在 'test-realm' 域中创建一个用户名为 'newUser'，邮箱为 '[email protected]'，名为 'Test'，姓为 'User' 的用户"。LLM 客户端会将此指令转换为对 'create-user' 工具的调用，并将 'realm', 'username', 'email', 'firstName', 'lastName' 作为参数传递给 MCP 服务器。
- 让 LLM "列出所有 Keycloak 域"。LLM 客户端会调用 'list-realms' 工具，MCP 服务器会返回 Keycloak 中所有域的列表。
具体的工具名称和输入参数可以参考仓库 README.md 文件中 "Available Tools" 部分的描述。

关键词