Advanced Keycloak Mcp Server

Octodet Keycloak MCP Server

Keycloak を管理するための強力な Model Context Protocol サーバーです。LLM インターフェースを通じて、ユーザー、レルム、ロール、その他の Keycloak リソースを管理するための包括的なツールセットを提供します。

機能

• ユーザー管理：レルム全体でユーザーを作成、削除、一覧表示します
• レルム管理：包括的なレルム管理機能を提供します
• 安全な統合：管理者の認証情報で認証します
• 簡単な設定：環境変数を使って簡単にセットアップできます
• LLM 統合：Claude、ChatGPT、その他の MCP 対応 AI アシスタントでシームレスに使用できます

インストール

NPM 経由（推奨）

このサーバーは NPM パッケージとして利用できます。

# Direct usage with npx
npx -y @octodet/keycloak-mcp

# Or global installation
npm install -g @octodet/keycloak-mcp

設定

環境変数

変数	説明	デフォルト
KEYCLOAK_URL	Keycloak サーバーの URL	http://localhost:8080
KEYCLOAK_ADMIN	管理者のユーザー名	admin
KEYCLOAK_ADMIN_PASSWORD	管理者のパスワード	admin
KEYCLOAK_REALM	デフォルトのレルム	master

MCP クライアントの設定

VS Code

次の内容を settings.json に追加します。

{
  "mcp.servers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "@octodet/keycloak-mcp"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

Claude Desktop

Claude Desktop の設定ファイルで設定します。

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["-y", "@octodet/keycloak-mcp"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

ローカル開発の場合

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

利用可能なツール

このサーバーは、Keycloak 管理用の包括的な MCP ツールセットを提供します。各ツールは、レルム、ユーザー、ロールに関する特定の管理タスクを実行するように設計されています。

📋 ツールの概要

ツール	カテゴリ	説明
create-user	ユーザー管理	指定したレルムに新しいユーザーを作成します
delete-user	ユーザー管理	レルムから既存のユーザーを削除します
list-users	ユーザー管理	指定したレルムのすべてのユーザーを一覧表示します
list-realms	レルム管理	利用可能なすべてのレルムを一覧表示します
list-roles	ロール管理	特定のクライアントのすべてのロールを一覧表示します
update-user-roles	ロール管理	ユーザーのクライアントロールを追加または削除します

---

👥 ユーザー管理

create-user

包括的なユーザー属性と任意の認証情報を指定して、指定したレルムに新しいユーザーを作成します。

必須パラメーター：

• realm（string）：対象のレルム名
• username（string）：新しいユーザーの一意のユーザー名
• email（string）：有効なメールアドレス
• firstName（string）：ユーザーの名
• lastName（string）：ユーザーの姓

任意のパラメーター：

• enabled（boolean）：ユーザーアカウントを有効または無効にします（デフォルト：true）
• emailVerified（boolean）：メールアドレスを確認済みとしてマークします
• credentials（array）：パスワード設定用の認証情報オブジェクトの配列

認証情報オブジェクトの構造：

• type（string）：認証情報の種類（例：「password」）
• value（string）：認証情報の値
• temporary（boolean）：初回ログイン時にパスワードの変更が必要かどうか

使用例：

{
  "realm": "my-app-realm",
  "username": "john.doe",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "enabled": true,
  "emailVerified": true,
  "credentials": [
    {
      "type": "password",
      "value": "TempPassword123!",
      "temporary": true
    }
  ]
}

応答： 作成されたユーザー ID と確認メッセージを返します。

---

delete-user

指定されたレルムからユーザーを完全に削除します。この操作は取り消せません。

必須パラメーター：

• realm（string）：対象のレルム名
• userId（string）：削除するユーザーの一意な識別子

使用例：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c"
}

応答： 削除が成功したことを示す確認メッセージです。

⚠️ 警告： この操作は取り消せません。実行前に、ユーザー ID が正しいことを確認してください。

---

list-users

指定されたレルム内のすべてのユーザーと、その基本情報の一覧を取得します。

必須パラメーター：

• realm（string）：対象のレルム名

使用例：

{
  "realm": "my-app-realm"
}

応答： レルム内のすべてのユーザーのユーザー名とユーザー ID を示す、書式設定された一覧を返します。

---

🏛️ レルム管理

list-realms

Keycloak インスタンスで利用可能なすべてのレルムを取得します。

パラメーター： 必須項目なし

使用例：

{}

応答： Keycloak のインストール環境で利用可能なすべてのレルム名の一覧を返します。

使用例：

• 利用可能なレルムの確認
• 他の操作を行う前のレルム名の検証
• Keycloak 設定の管理者向け概要の確認

---

🔐 ロール管理

list-roles

レルム内の特定のクライアントに定義されているすべてのロールを一覧表示します。割り当て前に利用可能な権限とロールを確認するのに便利です。

必須パラメーター：

• realm（string）：対象のレルム名
• clientId（string）：対象クライアントのクライアント ID または UUID

使用例：

{
  "realm": "my-app-realm",
  "clientId": "my-application"
}

クライアント UUID を使用する場合の例：

{
  "realm": "my-app-realm",
  "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

応答： 指定されたクライアントで利用可能なすべてのロール名の、書式設定された一覧を返します。

💡 ヒント： 人間が読みやすいクライアント ID と UUID のどちらも使用できます。

---

update-user-roles

ユーザーのクライアントロールの割り当てを管理します。1 回の操作でロールの追加と削除の両方を行えます。

必須パラメーター：

• realm（string）：対象のレルム名
• userId（string）：ユーザーの一意な識別子
• clientId（string）：クライアント ID または UUID

任意のパラメーター：

• rolesToAdd（array）：ユーザーに割り当てるロール名の一覧
• rolesToRemove（array）：ユーザーから削除するロール名の一覧

使用例 — ロールの追加：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToAdd": ["admin", "user-manager", "report-viewer"]
}

使用例 — ロールの削除：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToRemove": ["temporary-access", "beta-tester"]
}

使用例 — 追加と削除を組み合わせた操作：

{
  "realm": "my-app-realm",
  "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c",
  "clientId": "my-application",
  "rolesToAdd": ["senior-user"],
  "rolesToRemove": ["junior-user", "trainee"]
}

応答： 追加および削除されたロールと、発生したエラーの詳細な概要を返します。

🔍 注意事項：

• rolesToAdd または rolesToRemove の少なくとも一方を指定する必要があります
• 存在しないロールは警告とともにスキップされます
• 操作はロールリストごとにアトミックに実行されます（操作の種類ごとに、すべて実行されるか、まったく実行されないかのどちらかです）

---

🚀 使用上のヒント

1. ユーザー ID とユーザー名： ほとんどの操作で必要なのはユーザー名ではなく、ユーザー ID（UUID）です。正しいユーザー ID を確認するには list-users を使用してください。

2. クライアントの識別： clientId パラメーターには、人間が読みやすいクライアント ID と UUID のどちらも指定できます。

3. レルムの検証： 操作を行う前に、必ず list-realms を使用してレルム名を確認してください。

4. ロールの確認： ロールを割り当てる前に、list-roles を使用して利用可能なロールを確認してください。

5. エラー処理： すべてのツールが、認証、権限、パラメーターの問題を解決するための詳細なエラーメッセージを提供します。

開発

開発環境のセットアップ

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Start the development server with watch mode
npm run watch

新しいツールの追加

サーバーに新しいツールを追加するには：

1. Zod を使用して src/index.ts にツールスキーマを定義します
2. ListToolsRequestSchema ハンドラーにツール定義を追加します
3. CallToolRequestSchema の switch 文にツールハンドラーを実装します
4. 新しいツールについて説明するため、この README を更新します

テスト

MCP Inspector の使用

MCP Inspector は、MCP サーバーのテストに便利なツールです。

npx -y @modelcontextprotocol/inspector npx -y @octodet/keycloak-mcp

統合テスト

ローカルの Keycloak インスタンスを使用したテストの場合：

# Start Keycloak with Docker
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

# In another terminal, run the MCP server
npm run build
node build/index.js

デプロイ

NPM パッケージ

このプロジェクトは @octodet/keycloak-mcp として NPM に公開されています。

自動デプロイ

このプロジェクトでは、GitHub Actions を CI/CD に使用しており、新しいリリースが作成されると自動的にテストを実行し、NPM に公開します。

前提条件

• Node.js 18 以降
• 起動中の Keycloak インスタンス

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については、LICENSE ファイルをご覧ください。

作者

Octodet - 開発者向けのインテリジェントなツールを構築