mcp-keycloak

mcp-keycloak

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

設計目標はデフォルトで安全であることです。読み取り専用で起動し、許可リストに登録されたレルムのみを対象とし、機密性の高いレルムへの変更を保護し、破壊的な操作は明示的なオプトインがないと実行できないようにします。

機能

• マルチレルム — すべてのツールで realm 引数を指定します。許可リストを使って対象を限定できます。
• アクセスモード — read-only → read-write → admin の順に機能が増えます。各モードで、そのレベルを超えるツールが公開されることはありません。
• セキュリティフラグ — レルムの許可リスト、保護対象レルム、削除の制御、ドライラン、JSON 監査ログに対応しています（以下を参照）。
• 2 種類の認証方式 — 機密クライアントのサービスアカウント（推奨）または管理者のユーザー名とパスワードを使用します。
• 重い依存関係なし — 軽量な fetch ベースの Admin REST クライアントに、MCP SDK と zod を使用します。

セキュリティモデル

懸念事項	フラグ	デフォルト	効果
サーバーで実行できる操作は何ですか？	KEYCLOAK_MODE	read-only	read-only では読み取りツールのみ、read-write では変更操作も、admin では破壊的なツールも使用できます。モードを超えるツールが登録されることはありません。
対象となるレルムはどれですか？	KEYCLOAK_REALM_ALLOWLIST	(すべて)	カンマ区切りです。設定すると、リスト外のレルムに対する操作は拒否されます。
常に読み取り専用となるレルムはどれですか？	KEYCLOAK_PROTECTED_REALMS	master	保護対象のレルムは読み取りできますが、モードにかかわらず変更や削除はできません。
削除を許可しますか？	KEYCLOAK_ALLOW_DELETE	false	delete_* ツールには、この設定と admin モードの両方が必要です。
Keycloak に変更を加えずにプレビューしますか？	KEYCLOAK_DRY_RUN	false	書き込み／管理者ツールは検証して意図をログに記録した後、Keycloak を呼び出さずに戻ります。
監査証跡	KEYCLOAK_AUDIT_LOG	true	保護対象の操作ごとに、stderr に JSON 行（ALLOW／DENY／DRY_RUN）を出力します。
対話型の確認	(自動)	—	破壊的な操作と影響の大きい操作を実行する前に、MCP elicitation を通じて人間に承認を求めます。elicitation に対応していないクライアントでは、*_ALLOW_* ゲートにフォールバックします。

これらのレイヤーはそれぞれ独立しています。たとえば、KEYCLOAK_ALLOW_DELETE=false の admin モードではユーザーの作成と更新はできますが、削除はできません。

ツール

読み取り（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

クイックスタート — エージェントに追加

npm で @dockndevai/mcp-keycloak として公開されています。クローンやビルドは不要です。MCP クライアントが必要に応じて npx で実行します。まずは read-only モードで開始してください。すべての変数は .env.example を、クライアントごとの詳しいガイドは docs/CLIENTS.md を参照してください。

Claude Code（CLI）

claude mcp add keycloak -e KEYCLOAK_URL="https://keycloak.example.com" -e KEYCLOAK_CLIENT_ID="admin-cli" -e KEYCLOAK_CLIENT_SECRET="your-secret" -e KEYCLOAK_MODE="read-only" -- npx -y @dockndevai/mcp-keycloak

Claude Desktop · Cursor · Windsurf — 同じブロックを claude_desktop_config.json、.cursor/mcp.json、または ~/.codeium/windsurf/mcp_config.json に設定します。

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-keycloak"
      ],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml に設定します。

[mcp_servers.keycloak]
command = "npx"
args = ["-y", "@dockndevai/mcp-keycloak"]
env = { KEYCLOAK_URL = "https://keycloak.example.com", KEYCLOAK_CLIENT_ID = "admin-cli", KEYCLOAK_CLIENT_SECRET = "your-secret", KEYCLOAK_MODE = "read-only" }

VS Code（GitHub Copilot、エージェントモード） — .vscode/mcp.json に設定します。

{
  "servers": {
    "keycloak": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-keycloak"
      ],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only"
      }
    }
  }
}

設定

.env.example をコピーして値を設定するか、MCP クライアントの設定に変数を直接指定してください。必要な realm-management ロールを持つ機密クライアントを認証情報として使用することを推奨します。

ソースから実行する（開発）

上記の公開パッケージを推奨します。クローンから実行するには：

npm install
npm run build
node dist/index.js   # with the environment variables set

開発

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