MCP Keycloak

🚀 Keycloak MCP Server

Model Context Protocol (MCP)サーバーで、REST APIを介してKeycloakのID管理とアクセス管理を自然言語で操作できます。このサーバーにより、AIエージェントはユーザー管理、クライアント設定、レルム管理、ロールベースのアクセス制御をシームレスに実行できます。

🚀 クイックスタート

Keycloak MCP Serverは、AIアプリケーションとKeycloakの強力なID管理機能を橋渡しします。ユーザー管理、クライアント設定、複雑な認可シナリオを扱う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 Serverは、機能別に整理された包括的なツールセットを提供します。

ユーザー管理

完全なユーザーライフサイクル管理を行います。

• 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 Serverを統合する前に、以下のいずれかをインストールしてください。

• 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パワードのID管理

自然言語コマンドを通じてユーザーオンボーディング、権限管理、アクセス制御を処理できるAIアシスタントを構築します。

🔄 自動ユーザープロビジョニング

ビジネスルールに基づいてユーザーを自動的にプロビジョニングし、ロールを割り当て、クライアントアプリケーションを設定するワークフローを作成します。

📊 ID分析

ユーザーデータ、セッション情報、アクセスパターンをクエリして分析し、IDインフラストラクチャに関する洞察を得ます。

🚀 DevOps統合

Keycloak管理をCI/CDパイプラインに統合し、IDサービスの自動構成を可能にします。

要件

• Python 3.8以上
• Keycloakサーバー (Keycloak 18+でテスト済み)
• Keycloakレルムへの管理者アクセス

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

コントリビューション

コントリビューションは歓迎されます！プルリクエストを送信してください。

サポート

問題、質問、またはコントリビューションについては、GitHubリポジトリをご覧ください。