MCP Keycloak

🚀 Keycloak MCP 服务器

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

🚀 快速开始

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

✨ 主要特性

🔐 全面的用户管理

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

🏢 客户端配置

创建和配置 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 文件配置服务器：

# 必需配置
SERVER_URL=https://your-keycloak-server.com
USERNAME=admin-username
PASSWORD=admin-password
REALM_NAME=your-realm

# 可选的 OAuth2 客户端配置
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 - 默认设置

💻 使用示例

运行服务器

直接启动 MCP 服务器：

python -m src.main

集成示例

前提条件

在集成 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 助手。

🔄 自动化用户预配

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

📊 身份分析

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

🚀 DevOps 集成

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

要求

• Python 3.8 或更高版本
• Keycloak 服务器（已在 Keycloak 18+ 上测试）
• Keycloak 领域的管理员访问权限

📄 许可证

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

贡献

欢迎贡献！请随时提交拉取请求。

支持

如有问题、疑问或贡献，请访问 GitHub 仓库。