Keycloak MCPサーバー

KeycloakのIDおよびアクセス管理をREST API経由で操作するための自然言語インターフェースを提供するModel Context Protocol (MCP) サーバーです。このサーバーを使用することで、AIエージェントはユーザー管理、クライアント設定、レルム管理、ロールベースのアクセス制御操作をシームレスに実行できます。

概要

Keycloak MCPサーバーは、AIアプリケーションとKeycloakの強力なID管理機能の橋渡しをします。ユーザー管理、クライアント設定、複雑な認可シナリオの処理が必要なAIアシスタントを構築する場合でも、このサーバーはシンプルな自然言語コマンドを通じて必要なツールを提供します。

Related MCP server: Advanced Keycloak MCP server

機能

🔐 包括的なユーザー管理

作成から削除までのユーザーライフサイクル管理、パスワードリセット、セッション管理、ユーザー属性の更新などを行います。

🏢 クライアント設定

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 ファイルを使用して設定できます：

# Required configuration
SERVER_URL=https://your-keycloak-server.com
USERNAME=admin-username
PASSWORD=admin-password
REALM_NAME=your-realm

# Optional OAuth2 client configuration
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 - デフォルト設定

認証管理

完全な認証フロー制御：

• list_authentication_flows / get_authentication_flow - フロー管理

• create_authentication_flow / update_authentication_flow - フローCRUD操作

• delete_authentication_flow / copy_authentication_flow - フローの変更

• get_flow_executions / update_flow_executions - 実行管理

• create_execution / delete_execution - 実行ライフサイクル

• get_authenticator_config / create_authenticator_config - 設定管理

• get_required_actions / update_required_action - 必須アクション制御

使用方法

サーバーの実行

サーバーはstdio（デフォルト）とHTTPトランスポートの両方をサポートしています。smithery.yaml設定ファイルにより、SmitheryプラットフォームへのデプロイとSmithery CLI経由の自動インストールが可能です：

# Run in stdio mode (default, for local CLI tools)
python -m src.main

# Run in HTTP mode with streamable HTTP transport
TRANSPORT=http python -m src.main

# Run HTTP mode on a custom port
TRANSPORT=http PORT=8080 python -m src.main

# Or use the convenience script:
./scripts/run_server.sh         # stdio mode (default)
./scripts/run_server.sh http    # HTTP mode
PORT=8080 ./scripts/run_server.sh http  # HTTP mode on custom port

HTTPトランスポートを使用する場合、サーバーには http://127.0.0.1:8000/mcp/ （またはカスタムPORT）からアクセス可能です。

HTTPトランスポート

Keycloak MCPサーバーはHTTPトランスポートモードをサポートしており、いくつかの利点があります：

• ネットワークアクセス性: ネットワーク上のどのマシンからでもサーバーにアクセス可能

• 複数のクライアント: 複数のAIクライアントからの同時接続をサポート

• 統合の柔軟性: WebアプリケーションやAPIとの統合が容易

• 負荷分散: スケーラビリティのためにリバースプロキシの背後にデプロイ可能

HTTPプロトコルの詳細

HTTPトランスポートは、Streamable HTTPのMCP仕様に従います。FastMCPはすべてのプロトコル要件を自動的に処理します：

• エンドポイント: すべての通信は /mcp/ エンドポイントを通じて行われます

• リクエストメソッド: JSON-RPC 2.0メッセージを含むPOSTリクエスト

• コンテンツタイプ:

  • サーバーは単一のレスポンスに対して Content-Type: application/json を返します

  • サーバーはストリーミングレスポンスに対して Content-Type: text/event-stream を返します

• Acceptヘッダー: クライアントは Accept: application/json, text/event-stream を含める必要があります

• メッセージ形式: すべてのメッセージはUTF-8エンコードされたJSON-RPC 2.0形式を使用します

FastMCPは、リクエストタイプとレスポンスにストリーミング機能が必要かどうかに基づいて、単一のJSONレスポンスを返すかSSEストリームを返すかを自動的に判断します。

HTTPサーバーへの接続

HTTPモードで実行する場合、クライアントは以下に接続できます：

http://127.0.0.1:8000/mcp/

クライアントリクエストの例：

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "list_tools", "id": 1}'

セキュリティの実装

HTTPトランスポートは、すべてのMCP仕様のセキュリティ要件を実装しています：

✅ Originヘッダーの検証 (必須)

• DNSリバインディング攻撃を防ぐためにOriginヘッダーを自動的に検証します

• localhost および 127.0.0.1 オリジンからの接続のみを許可します

• 許可されていないクロスオリジンリクエストをブロックします

✅ Localhostバインディング (推奨)

• ネットワークベースの攻撃を防ぐために 127.0.0.1 にのみバインドします

• MCP仕様のセキュリティ推奨事項に従います

✅ 認証不要

• サーバーはローカル開発を簡素化するために認証要件なしで実行されます

• localhostでの使用や信頼された環境に適しています

本番環境へのデプロイでは、以下の追加の考慮事項があります：

• 適切な証明書を使用してHTTPSを使用する

• リバースプロキシ（nginx、Apache）の背後にデプロイする

• 適切なファイアウォールルールを設定する

• 必要に応じてリバースプロキシレベルで認証を実装する

統合例

前提条件

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を活用したID管理

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

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

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

📊 ID分析

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

🚀 DevOps統合

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

要件

• Python 3.8以上

• Keycloakサーバー (Keycloak 18+でテスト済み)

• Keycloakレルムへの管理者アクセス権

ライセンス

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

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

サポート

問題、質問、貢献については、GitHubリポジトリ をご覧ください。