Keycloak MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供了一个自然语言接口，用于通过 REST API 管理 Keycloak 身份与访问管理。该服务器使 AI 代理能够无缝执行用户管理、客户端配置、领域管理和基于角色的访问控制操作。

概述

Keycloak MCP 服务器架起了 AI 应用程序与 Keycloak 强大身份管理功能之间的桥梁。无论您是在构建需要管理用户、配置客户端或处理复杂授权场景的 AI 助手，该服务器都能通过简单的自然语言命令为您提供所需的工具。

Related MCP server: Advanced Keycloak MCP server

功能

🔐 全面的用户管理

管理从创建到删除的用户生命周期，包括密码重置、会话管理和用户属性更新。

🏢 客户端配置

创建和配置 OAuth2/OIDC 客户端，管理客户端密钥，并以编程方式处理服务帐户。

👥 基于角色的访问控制

定义并分配领域和客户端特定的角色，管理用户权限，并实现细粒度的访问控制。

🏛️ 领域管理

配置领域设置、管理默认组、处理事件配置并控制整个领域的策略。

🔐 身份验证管理

全面的身份验证流程管理，包括创建、更新和删除流程，管理执行，以及配置身份验证器。

🔄 组管理

将用户组织到组中，管理组层次结构，并高效处理基于组的权限。

安装

通过 Smithery 安装

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

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

快速开始

使用 pip 安装：

pip install mcp-keycloak

开发安装

克隆存储库并安装依赖项：

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak
pip install -e .

配置

可以使用环境变量或 .env 文件配置服务器：

# Required configuration
SERVER_URL=https://your-keycloak-server.com
USERNAME=admin-username
PASSWORD=admin-password
REALM_NAME=your-realm

# Optional OAuth2 client configuration
CLIENT_ID=optional-client-id
CLIENT_SECRET=optional-client-secret

工具

Keycloak MCP 服务器提供了一套按功能组织的全面工具：

用户管理

完整的用户生命周期管理，包括：

• list_users - 列出用户（支持分页和过滤）

• create_user / update_user / delete_user - 完整的 CRUD 操作

• reset_user_password - 密码管理

• get_user_sessions / logout_user - 会话控制

• count_users - 用户统计

客户端管理

OAuth2/OIDC 客户端配置：

• list_clients / get_client / create_client - 客户端操作

• get_client_secret / regenerate_client_secret - 密钥管理

• get_client_service_account - 服务帐户访问

• update_client / delete_client - 客户端修改

角色管理

细粒度的权限控制：

• list_realm_roles / create_realm_role - 领域角色操作

• list_client_roles / create_client_role - 客户端特定角色

• assign_realm_role_to_user / remove_realm_role_from_user - 角色分配

• get_user_realm_roles / assign_client_role_to_user - 用户角色查询

组管理

分层用户组织：

• list_groups / create_group / update_group - 组操作

• get_group_members / add_user_to_group - 成员资格管理

• get_user_groups / remove_user_from_group - 用户组关联

领域管理

系统级配置：

• get_accessible_realms - 可访问领域列表

• get_realm_info / update_realm_settings - 领域配置

• get_realm_events_config / update_realm_events_config - 事件管理

• add_realm_default_group / remove_realm_default_group - 默认设置

身份验证管理

完整的身份验证流程控制：

• list_authentication_flows / get_authentication_flow - 流程管理

• create_authentication_flow / update_authentication_flow - 流程 CRUD 操作

• delete_authentication_flow / copy_authentication_flow - 流程修改

• get_flow_executions / update_flow_executions - 执行管理

• create_execution / delete_execution - 执行生命周期

• get_authenticator_config / create_authenticator_config - 配置管理

• get_required_actions / update_required_action - 所需操作控制

使用

运行服务器

服务器支持 stdio（默认）和 HTTP 传输。smithery.yaml 配置文件支持在 Smithery 平台上部署以及通过 Smithery CLI 自动安装：

# Run in stdio mode (default, for local CLI tools)
python -m src.main

# Run in HTTP mode with streamable HTTP transport
TRANSPORT=http python -m src.main

# Run HTTP mode on a custom port
TRANSPORT=http PORT=8080 python -m src.main

# Or use the convenience script:
./scripts/run_server.sh         # stdio mode (default)
./scripts/run_server.sh http    # HTTP mode
PORT=8080 ./scripts/run_server.sh http  # HTTP mode on custom port

使用 HTTP 传输时，可以通过 http://127.0.0.1:8000/mcp/（或您的自定义端口）访问服务器。

HTTP 传输

Keycloak MCP 服务器支持 HTTP 传输模式，具有以下优势：

• 网络可访问性：从网络上的任何机器访问服务器

• 多客户端：支持来自多个 AI 客户端的并发连接

• 集成灵活性：易于与 Web 应用程序和 API 集成

• 负载均衡：部署在反向代理后以实现可扩展性

HTTP 协议详情

HTTP 传输遵循 Streamable HTTP 的 MCP 规范。FastMCP 会自动处理所有协议要求：

• 端点：所有通信均通过 /mcp/ 端点进行

• 请求方法：带有 JSON-RPC 2.0 消息的 POST 请求

• 内容类型：

  • 服务器为单个响应返回 Content-Type: application/json

  • 服务器为流式响应返回 Content-Type: text/event-stream

• Accept 标头：客户端必须包含 Accept: application/json, text/event-stream

• 消息格式：所有消息均使用 JSON-RPC 2.0 格式，UTF-8 编码

FastMCP 会根据请求类型以及响应是否需要流式传输能力，自动确定是返回单个 JSON 响应还是 SSE 流。

连接到 HTTP 服务器

在 HTTP 模式下运行时，客户端可以连接到：

http://127.0.0.1:8000/mcp/

客户端请求示例：

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "list_tools", "id": 1}'

安全实现

HTTP 传输实现了所有 MCP 规范的安全要求：

✅ Origin 标头验证（必需）

• 自动验证 Origin 标头以防止 DNS 重绑定攻击

• 仅允许来自 localhost 和 127.0.0.1 源的连接

• 阻止未经授权的跨源请求

✅ 本地主机绑定（推荐）

• 仅绑定到 127.0.0.1 以防止基于网络的攻击

• 遵循 MCP 规范的安全建议

✅ 无需身份验证

• 服务器在运行时无需身份验证要求，以简化本地开发

• 适用于 localhost 使用和受信任的环境

对于生产部署，请考虑以下事项：

• 使用带有正确证书的 HTTPS

• 部署在反向代理（nginx、Apache）后

• 设置适当的防火墙规则

• 如有必要，在反向代理级别实现身份验证

集成示例

先决条件

在集成 Keycloak MCP 服务器之前，请确保已安装以下其中一项：

• uvx（推荐）：通过 pip install uvx 或 pipx install uvx 安装

• uv：遵循 安装说明

• npm/npx：用于 Smithery 安装（随 Node.js 提供）

选项 1：使用 Smithery CLI（推荐）

最简单的方法 - 自动为 Claude Desktop 配置所有内容：

npx @smithery/cli install @idoyudha/mcp-keycloak --client claude

此命令将提示您输入所需的配置值并自动设置服务器。

选项 2：使用 uvx（手动设置）

无需克隆！添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "keycloak": {
      "command": "uvx",
      "args": ["mcp-keycloak"],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

选项 3：本地开发设置

用于开发或自定义：

1. 克隆存储库：

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak

2. 添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-keycloak",
        "run",
        "python",
        "-m",
        "src"
      ],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

💡 快速提示：

• 将 /path/to/mcp-keycloak 替换为您克隆存储库的实际路径

• 确保您的 Keycloak 服务器 URL 包含协议（https:// 或 http://）

• REALM_NAME 应与您 Keycloak 实例中现有的领域匹配

示例用例

🤖 AI 驱动的身份管理

构建 AI 助手，通过自然语言命令处理用户入职、权限管理和访问控制。

🔄 自动化用户配置

创建工作流，根据业务规则自动配置用户、分配角色并配置客户端应用程序。

📊 身份分析

查询和分析用户数据、会话信息和访问模式，以深入了解您的身份基础设施。

🚀 DevOps 集成

将 Keycloak 管理集成到您的 CI/CD 管道中，实现身份服务的自动化配置。

要求

• Python 3.8 或更高版本

• Keycloak 服务器（已在 Keycloak 18+ 上测试）

• Keycloak 领域的管理员访问权限

许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时提交 Pull Request。

支持

有关问题、疑问或贡献，请访问 GitHub 存储库。