mcp-keycloak

Keycloak 用の Model Context Protocol サーバーです。MCP 対応クライアント（Claude Desktop、Claude Code など）から Keycloak のレルム、ユーザー、クライアント、ロール、グループを調査・管理できるようにします。セキュリティはすべてフラグで制御されます。

設計方針は 安全優先（safe by default） です。読み取り専用で起動し、許可リストに登録された realm にスコープを制限し、重要な realm を変更から保護し、破壊的な操作は明示的なオプトインを必須とします。

機能

• マルチ realm — すべてのツールは realm 引数を受け取ります。許可リストでスコープを制限できます。

• アクセスモード — read-only → read-write → admin の階層型で、各モードは自分のレベルより上のツールを公開しません。

• セキュリティフラグ — realm 許可リスト、保護された realm、削除のゲート、ドライラン、JSON 監査ログ（下記参照）。

• 2 つの認証戦略 — 機密クライアントのサービスアカウント（推奨）または管理者のユーザー名/パスワード。

• 重い依存関係なし — 軽量な fetch ベースの Admin REST クライアントに加え、MCP SDK と zod のみ。

Related MCP server: mcp-keycloak-admin

セキュリティモデル

これらの層は独立しています。たとえば admin モードで KEYCLOAK_ALLOW_DELETE=false の場合、ユーザーを作成・更新できますが削除はできません。

ツール

読み取り（read-only 以上）: list_realms、get_realm、list_users、get_user、count_users、list_clients、list_realm_roles、list_groups

書き込み（read-write 以上）: create_user、update_user、reset_password、logout_user

管理（admin）: delete_user

MCP クライアントでの使用

Claude Code、Claude Desktop、Cursor、OpenAI Codex CLI、Windsurf、VS Code（Copilot）、その他あらゆる MCP クライアントで利用できます。クライアント別の設定は docs/CLIENTS.md を参照してください。

インストール

npm install
npm run build

構成

.env.example をコピーして記入するか、MCP クライアント設定に直接変数を設定してください。必要に応じて realm-management ロールを持つ機密クライアントが推奨される認証情報です。

Claude Desktop / Claude Code で実行

MCP クライアント設定（claude_desktop_config.json または claude mcp add）に追加します:

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-keycloak/dist/index.js"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only",
        "KEYCLOAK_REALM_ALLOWLIST": "app,customers"
      }
    }
  }
}

変更をモデルに許可する場合にのみ、KEYCLOAK_MODE を read-write（削除の場合は admin + KEYCLOAK_ALLOW_DELETE=true）に上げてください。

開発

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

公開

このサーバーは、公式 MCP レジストリ向けの server.json と、npm の所有権検証用の mcpName を同梱しています。npm への公開と MCP レジストリ、Smithery、Glama、Cursor、PulseMCP への登録については、PUBLISHING.md を参照してください。

ライセンス

MIT