Advanced Keycloak Mcp Server

Available Tools

The server provides a comprehensive set of MCP tools for Keycloak administration. Each tool is designed to perform specific administrative tasks across realms, users, and roles.

📋 Tool Overview

Tool	Category	Description
create-user	User Management	Create a new user in a specified realm
delete-user	User Management	Delete an existing user from a realm
list-users	User Management	List all users in a specified realm
list-realms	Realm Management	List all available realms
list-roles	Role Management	List all roles for a specific client
update-user-roles	Role Management	Add or remove client roles for a user

---

👥 User Management

create-user

Creates a new user in a specified realm with comprehensive user attributes and optional credentials.

Required Parameters:

• realm (string): Target realm name
• username (string): Unique username for the new user
• email (string): Valid email address
• firstName (string): User's first name
• lastName (string): User's last name

Optional Parameters:

• enabled (boolean): Enable/disable user account (default: true)
• emailVerified (boolean): Mark email as verified
• credentials (array): Array of credential objects for setting passwords

Credential Object Structure:

• type (string): Credential type (e.g., "password")
• value (string): The credential value
• temporary (boolean): Whether password must be changed on first login

Example Usage:

{
  "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
    }
  ]
}

Response: Returns the created user ID and confirmation message.

---

delete-user

Permanently removes a user from the specified realm. This action cannot be undone.

Required Parameters:

• realm (string): Target realm name
• userId (string): Unique identifier of the user to delete

Example Usage:

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

Response: Confirmation message of successful deletion.

⚠️ Warning: This operation is irreversible. Ensure you have the correct user ID before execution.

---

list-users

Retrieves a list of all users in the specified realm with their basic information.

Required Parameters:

• realm (string): Target realm name

Example Usage:

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

Response: Returns a formatted list showing usernames and user IDs for all users in the realm.

---

🏛️ Realm Management

list-realms

Retrieves all available realms in the Keycloak instance.

Parameters: None required

Example Usage:

{}

Response: Returns a list of all realm names available in the Keycloak installation.

Use Cases:

• Discovering available realms
• Validating realm names before other operations
• Administrative overview of the Keycloak setup

---

🔐 Role Management

list-roles

Lists all roles defined for a specific client within a realm. Useful for understanding available permissions and roles before assignment.

Required Parameters:

• realm (string): Target realm name
• clientId (string): Client ID or UUID of the target client

Example Usage:

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

Alternative with Client UUID:

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

Response: Returns a formatted list of all role names available for the specified client.

💡 Tip: You can use either the client's human-readable ID or its UUID identifier.

---

update-user-roles

Manages client role assignments for a user. Allows both adding and removing roles in a single operation.

Required Parameters:

• realm (string): Target realm name
• userId (string): User's unique identifier
• clientId (string): Client ID or UUID

Optional Parameters:

• rolesToAdd (array): List of role names to assign to the user
• rolesToRemove (array): List of role names to remove from the user

Example Usage - Adding Roles:

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

Example Usage - Removing Roles:

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

Example Usage - Combined Operation:

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

Response: Detailed summary of roles added, removed, and any errors encountered.

🔍 Notes:

• At least one of rolesToAdd or rolesToRemove must be provided
• Non-existent roles are skipped with warnings
• The operation is atomic per role list (all or none for each operation type)

---