Keycloak MCP

🚀 Octodet Keycloak MCP 服務器

Octodet Keycloak MCP 服務器是一款強大的用於 Keycloak 管理的模型上下文協議（MCP）服務器。它提供了一套全面的工具，可通過大語言模型（LLM）接口管理用戶、領域、角色和其他 Keycloak 資源。

✨ 主要特性

• 用戶管理：跨領域創建、刪除和列出用戶。
• 領域管理：具備全面的領域管理能力。
• 安全集成：使用管理員憑證進行身份驗證。
• 輕鬆配置：通過環境變量進行簡單設置。
• LLM 集成：可與 Claude、ChatGPT 等支持 MCP 的 AI 助手無縫協作。

📦 安裝指南

通過 NPM（推薦）

該服務器以 NPM 包的形式提供：

# 使用 npx 直接運行
npx -y @octodet/keycloak-mcp

# 或者全局安裝
npm install -g @octodet/keycloak-mcp

📚 詳細文檔

配置

環境變量

MCP 客戶端配置

VS Code

將以下內容添加到 settings.json 中：

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

Claude Desktop

在 Claude Desktop 配置文件中進行配置：

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

本地開發

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

可用工具

該服務器提供了一套全面的 MCP 工具，用於 Keycloak 管理。每個工具都旨在跨領域、用戶和角色執行特定的管理任務。

📋 工具概述

👥 用戶管理

create-user

在指定領域中創建具有全面用戶屬性和可選憑證的新用戶。

必需參數：

• realm（字符串）：目標領域名稱
• username（字符串）：新用戶的唯一用戶名
• email（字符串）：有效的電子郵件地址
• firstName（字符串）：用戶的名字
• lastName（字符串）：用戶的姓氏

可選參數：

• enabled（布爾值）：啟用/禁用用戶賬戶（默認：true）
• emailVerified（布爾值）：將電子郵件標記為已驗證
• credentials（數組）：用於設置密碼的憑證對象數組

憑證對象結構：

• type（字符串）：憑證類型（例如，"password"）
• value（字符串）：憑證值
• temporary（布爾值）：密碼是否必須在首次登錄時更改

使用示例：

{
  "realm": "my-app-realm",
  "username": "john.doe",
  "email": "john.doe@company.com",
  "firstName": "John",
  "lastName": "Doe",
  "enabled": true,
  "emailVerified": true,
  "credentials": [
    {
      "type": "password",
      "value": "TempPassword123!",
      "temporary": true
    }
  ]
}

響應：返回創建的用戶 ID 和確認消息。

delete-user

從指定領域中永久刪除用戶。此操作無法撤銷。

必需參數：

• realm（字符串）：目標領域名稱
• userId（字符串）：要刪除的用戶的唯一標識符

使用示例：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c"
}

響應：成功刪除的確認消息。

⚠️ 重要提示

此操作不可逆。在執行之前，請確保您擁有正確的用戶 ID。

list-users

檢索指定領域中所有用戶的基本信息列表。

必需參數：

• realm（字符串）：目標領域名稱

使用示例：

{
  "realm": "my-app-realm"
}

響應：返回該領域中所有用戶的用戶名和用戶 ID 的格式化列表。

🏛️ 領域管理

list-realms

檢索 Keycloak 實例中所有可用的領域。

參數：無需參數

使用示例：

{}

響應：返回 Keycloak 安裝中所有領域名稱的列表。

使用場景：

• 發現可用領域
• 在執行其他操作之前驗證領域名稱
• 對 Keycloak 設置進行管理概述

🔐 角色管理

list-roles

列出領域內特定客戶端定義的所有角色。有助於在分配角色之前瞭解可用的權限和角色。

必需參數：

• realm（字符串）：目標領域名稱
• clientId（字符串）：目標客戶端的客戶端 ID 或 UUID

使用示例：

{
  "realm": "my-app-realm",
  "clientId": "my-application"
}

使用客戶端 UUID 的替代示例：

{
  "realm": "my-app-realm",
  "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

響應：返回指定客戶端可用的所有角色名稱的格式化列表。

💡 使用建議

您可以使用客戶端的可讀 ID 或其 UUID 標識符。

update-user-roles

管理用戶的客戶端角色分配。允許在單個操作中添加和刪除角色。

必需參數：

• realm（字符串）：目標領域名稱
• userId（字符串）：用戶的唯一標識符
• clientId（字符串）：客戶端 ID 或 UUID

可選參數：

• rolesToAdd（數組）：要分配給用戶的角色名稱列表
• rolesToRemove（數組）：要從用戶中刪除的角色名稱列表

添加角色的使用示例：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToAdd": ["admin", "user-manager", "report-viewer"]
}

刪除角色的使用示例：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToRemove": ["temporary-access", "beta-tester"]
}

組合操作的使用示例：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToAdd": ["senior-user"],
  "rolesToRemove": ["junior-user", "trainee"]
}

響應：詳細總結添加、刪除的角色以及遇到的任何錯誤。

🔍 注意事項：

• 必須提供 rolesToAdd 或 rolesToRemove 中的至少一個
• 不存在的角色將被跳過並給出警告
• 每個角色列表的操作是原子性的（每種操作類型要麼全部執行，要麼全部不執行）

🚀 使用提示

1. 用戶 ID 與用戶名：大多數操作需要用戶 ID（UUID），而不是用戶名。使用 list-users 查找正確的用戶 ID。
2. 客戶端標識：clientId 參數接受可讀的客戶端 ID 和 UUID 標識符。
3. 領域驗證：在執行操作之前，始終使用 list-realms 驗證領域名稱。
4. 角色發現：在嘗試分配角色之前，使用 list-roles 發現可用角色。
5. 錯誤處理：所有工具都提供詳細的錯誤消息，用於排查身份驗證、權限或參數問題。

開發

設置開發環境

# 克隆倉庫
git clone <repository-url>

# 安裝依賴
npm install

# 以監視模式啟動開發服務器
npm run watch

添加新工具

要向服務器添加新工具：

1. 使用 Zod 在 src/index.ts 中定義工具模式
2. 將工具定義添加到 ListToolsRequestSchema 處理程序中
3. 在 CallToolRequestSchema 開關語句中實現工具處理程序
4. 更新此 README 以記錄新工具

測試

使用 MCP 檢查器

MCP 檢查器是測試 MCP 服務器的好工具：

npx -y @modelcontextprotocol/inspector npx -y @octodet/keycloak-mcp

集成測試

要使用本地 Keycloak 實例進行測試：

# 使用 Docker 啟動 Keycloak
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

# 在另一個終端中，運行 MCP 服務器
npm run build
node build/index.js

部署

NPM 包

該項目已發佈到 NPM，包名為 @octodet/keycloak-mcp。

自動部署

該項目使用 GitHub Actions 進行 CI/CD，在創建新版本時自動測試併發布到 NPM。

先決條件

• Node.js 18 或更高版本
• 運行中的 Keycloak 實例

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

作者

Octodet - 為開發者構建智能工具