Keycloak Mcp Server

Keycloak MCP サーバー

Model Context Protocol（MCP）サーバーです。Keycloak Admin REST APIを型付きのMCPツールとして公開します。すべてのAPIカテゴリーを網羅する299個のツールを備えています。

---

特長

• APIを完全に網羅：Keycloak Admin REST APIの全299エンドポイントに対応
• 2種類のトランスポート：stdio（Claude Code）およびSSE（GitHub Copilot、その他のMCPクライアント）
• 自動認証：パスワードフローとクライアント認証情報フローの両方に対応し、トークンを自動更新
• 設定不要のツール：各ツールは、完全な入力スキーマを備えた自己記述型です

APIカテゴリー

カテゴリー	ツール
攻撃検出	3
認証管理	38
クライアント証明書	6
クライアント初期アクセス	3
クライアント登録ポリシー	1
クライアントロールマッピング	10
クライアントスコープ	10
クライアント	33
コンポーネント	6
グループ	11
IDプロバイダー	15
キー	2
組織	13
プロトコルマッパー	14
レルム管理	37
ロール	28
IDによるロール	10
スコープマッピング	29
ユーザー	30
合計	299

デモ

(実際のプロンプト3つと、実行されたツールを紹介するGIFまたはスクリーンショットを追加してください！)

インストール

オプション1：uvxで直接実行（推奨）

astralのuvを使うと、手動でインストールせずにサーバーを直接実行できます：

uvx keycloak-mcp-server

(uvxを使用する場合、環境変数をインラインで渡すか、MCP設定ファイルに記載できます。)

オプション2：pipでインストール

グローバル環境または仮想環境へのインストールを希望する場合：

pip install git+https://github.com/paoloamato2/keycloak-mcp-server.git

オプション3：ソースからインストール（開発用）

git clone https://github.com/paoloamato2/keycloak-mcp-server.git
cd keycloak-mcp-server
uv pip install -e .

設定

環境変数を設定するか、.env.exampleをもとに.envファイルを作成してください：

# Required
export KEYCLOAK_URL=http://localhost:8080

# Authentication - Option A: Password flow
export KEYCLOAK_ADMIN_USERNAME=admin
export KEYCLOAK_ADMIN_PASSWORD=admin

# Authentication - Option B: Client credentials flow
export KEYCLOAK_CLIENT_ID=my-client
export KEYCLOAK_CLIENT_SECRET=my-secret

# Optional
export KEYCLOAK_ADMIN_REALM=master    # default: master
export KEYCLOAK_VERIFY_SSL=true       # default: true

使用方法

Claude Code（stdio）

Claude CodeのMCP設定（~/.claude/claude_desktop_config.jsonまたはプロジェクトレベル）に追加してください：

{
  "mcpServers": {
    "keycloak": {
      "command": "python",
      "args": ["-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

または、uvでインストールした場合：

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/keycloak-mcp-server", "python", "-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

GitHub Copilot（SSE）

SSEトランスポートでサーバーを起動します：

python -m keycloak_mcp_server --transport sse --port 8080

次に、GitHub CopilotのMCP設定（VS Codeのsettings.json）で設定します：

{
  "github.copilot.chat.mcpServers": {
    "keycloak": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

コマンドライン

# stdio mode (default)
python -m keycloak_mcp_server

# SSE mode
python -m keycloak_mcp_server --transport sse --host 0.0.0.0 --port 8080

# Using the entry point
keycloak-mcp-server --transport sse --port 8080

セキュリティと本番環境での推奨事項

⚠️ セキュリティ警告： この MCP サーバーは、機密性の高い書き込み操作（ユーザーの作成・削除、パスワードのリセット、レルムの管理など）を含む、Keycloak Admin REST API のすべてのエンドポイント（299 個のツール）を登録します。本番環境では、master レルムのスーパー管理者の認証情報を使用しないでください。

この MCP サーバーを AI アシスタントに接続する際は、最小権限の原則を厳守してください。

1. サービスアカウント（クライアント認証情報フロー）を使用する： Password フロー（KEYCLOAK_ADMIN_USERNAME / KEYCLOAK_ADMIN_PASSWORD）の使用は避けてください。代わりに、Service Accounts Enabled が有効な専用の Keycloak クライアントを作成し、KEYCLOAK_CLIENT_ID と KEYCLOAK_CLIENT_SECRET を使用してください。

2. 対象レルムを制限する： 特に必要な場合を除き、サーバーを master レルムに接続しないでください。AI アシスタントが管理する必要のある正確なレルムを KEYCLOAK_ADMIN_REALM に指定してください。

3. 必要なロールのみを付与する： MCP サービスアカウントには、必要最小限のロールのみを割り当ててください。

   • LLM がデータの読み取りのみを行う場合：view-users、view-clients、view-realm のみを割り当てます。
   • LLM がユーザーを管理する必要がある場合：manage-users のみを割り当てます。
   • リスクを十分に理解している場合を除き、AI に admin または realm-admin ロールを割り当てることは絶対に避けてください。

4. SSL を必ず検証する： 中間者（MITM）攻撃を防ぐため、本番環境では KEYCLOAK_VERIFY_SSL=true を有効にしたままにしてください。false に設定してよいのは、ローカル開発環境のみです。

使用例

接続すると、自然言語で Keycloak を操作できます。

• 「すべてのレルムを一覧表示して」 → list_realms を呼び出します
• 「master レルムに john というユーザーを作成して」 → create_user を呼び出します
• 「production レルムのすべてのクライアントを表示して」 → list_clients を呼び出します
• 「ユーザー X が持っているロールを教えて」 → get_user_role_mappings を呼び出します
• 「developers グループに admin ロールを追加して」 → add_group_realm_role_mappings を呼び出します

プロジェクト構成

src/keycloak_mcp_server/
├── __init__.py          # Package entry point
├── __main__.py          # CLI entry point
├── config.py            # Environment-based configuration
├── client.py            # Async HTTP client with auto-auth
├── server.py            # MCP server setup and tool registration
└── endpoints/           # Endpoint definitions by category
    ├── __init__.py      # Base classes (EndpointDef, Param)
    ├── attack_detection.py
    ├── authentication.py
    ├── certificates.py
    ├── client_initial_access.py
    ├── client_registration_policy.py
    ├── client_role_mappings.py
    ├── client_scopes.py
    ├── clients.py
    ├── component.py
    ├── groups.py
    ├── identity_providers.py
    ├── key.py
    ├── organizations.py
    ├── protocol_mappers.py
    ├── realms.py
    ├── roles.py
    ├── roles_by_id.py
    ├── scope_mappings.py
    └── users.py

ライセンス

MIT