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 倉庫。