Keycloak MCP

🚀 Octodet Keycloak MCP Server

Keycloak管理用の強力なモデルコンテキストプロトコルサーバーです。LLMインターフェースを通じて、ユーザー、リアルム、ロールなどのKeycloakリソースを管理する包括的なツールセットを提供します。

✨ 主な機能

• ユーザー管理：複数のリアルムにまたがってユーザーを作成、削除、一覧表示できます。
• リアルム管理：包括的なリアルム管理機能を備えています。
• 安全な統合：管理者資格情報による認証が可能です。
• 簡単な設定：環境変数を使用したシンプルなセットアップが可能です。
• LLM統合：Claude、ChatGPT、その他のMCP互換AIアシスタントとシームレスに連携できます。

📦 インストール

NPM経由（推奨）

このサーバーはNPMパッケージとして提供されています。

# npxで直接使用
npx -y @octodet/keycloak-mcp

# またはグローバルインストール
npm install -g @octodet/keycloak-mcp

📚 ドキュメント

環境変数

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

指定されたリアルムに、包括的なユーザー属性とオプションの資格情報を持つ新しいユーザーを作成します。

必須パラメーター：

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

オプションパラメーター：

• enabled（ブール値）：ユーザーアカウントを有効/無効にする（デフォルト：true）
• emailVerified（ブール値）：メールを検証済みとしてマークする
• credentials（配列）：パスワードを設定するための資格情報オブジェクトの配列

資格情報オブジェクトの構造：

• type（文字列）：資格情報のタイプ（例："password"）
• value（文字列）：資格情報の値
• temporary（ブール値）：初回ログイン時にパスワードを変更する必要があるかどうか

使用例：

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

レスポンス：作成されたユーザーIDと確認メッセージを返します。

delete-user

指定されたリアルムからユーザーを永久に削除します。この操作は元に戻せません。

必須パラメーター：

• realm（文字列）：対象のリアルム名
• userId（文字列）：削除するユーザーの一意の識別子

使用例：

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

レスポンス：削除成功の確認メッセージを返します。

⚠️ 重要提示

この操作は元に戻せません。実行前に正しいユーザーIDを確認してください。

list-users

指定されたリアルム内のすべてのユーザーの基本情報を取得します。

必須パラメーター：

• realm（文字列）：対象のリアルム名

使用例：

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

レスポンス：リアルム内のすべてのユーザーのユーザー名とユーザーIDを表示する整形されたリストを返します。

🏛️ リアルム管理

list-realms

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

パラメーター：不要

使用例：

{}

レスポンス：Keycloakインストール内のすべてのリアルム名のリストを返します。

使用例：

• 利用可能なリアルムを探索する
• 他の操作を実行する前にリアルム名を検証する
• Keycloak設定の管理概要を取得する

🔐 ロール管理

list-roles

リアルム内の特定のクライアントに定義されたすべてのロールを一覧表示します。ロールの割り当て前に利用可能な権限とロールを理解するのに役立ちます。

必須パラメーター：

• realm（文字列）：対象のリアルム名
• clientId（文字列）：対象のクライアントのクライアント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

ユーザーのクライアントロールの割り当てを管理します。単一の操作でロールの追加と削除の両方が可能です。

必須パラメーター：

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

オプションパラメーター：

• rolesToAdd（配列）：ユーザーに割り当てるロール名のリスト
• rolesToRemove（配列）：ユーザーから削除するロール名のリスト

ロール追加の使用例：

{
  "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）が必要です。list-usersを使用して正しいユーザーIDを見つけてください。
2. クライアント識別：clientIdパラメーターは、人間が読めるクライアントIDとUUID識別子の両方を受け入れます。
3. リアルム検証：操作を実行する前に、常にlist-realmsを使用してリアルム名を検証してください。
4. ロール探索：ロールの割り当てを試みる前に、list-rolesを使用して利用可能なロールを探索してください。
5. エラー処理：すべてのツールは、認証、権限、またはパラメーターの問題をトラブルシューティングするための詳細なエラーメッセージを提供します。

🔧 開発

開発環境のセットアップ

# リポジトリをクローン
git clone <repository-url>

# 依存関係をインストール
npm install

# ウォッチモードで開発サーバーを起動
npm run watch

新しいツールの追加

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

1. src/index.tsでZodを使用してツールスキーマを定義します。
2. ListToolsRequestSchemaハンドラーにツール定義を追加します。
3. CallToolRequestSchemaスイッチ文でツールハンドラーを実装します。
4. このREADMEを更新して、新しいツールをドキュメント化します。

🧪 テスト

MCPインスペクターの使用

MCPインスペクターは、MCPサーバーをテストするのに便利なツールです。

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

統合テスト

ローカルのKeycloakインスタンスでテストするには：

# DockerでKeycloakを起動
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

# 別のターミナルで、MCPサーバーを実行
npm run build
node build/index.js

🚀 デプロイ

NPMパッケージ

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

自動デプロイ

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

前提条件

• Node.js 18以上
• 実行中のKeycloakインスタンス

📄 ライセンス

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

📝 作者

Octodet - 開発者向けのインテリジェントツールを構築しています。