Advanced Keycloak Mcp Server

A powerful Model Context Protocol server for Keycloak administration, providing a comprehensive set of tools to manage users, realms, roles, and other Keycloak resources through LLM interfaces.

- User Management: Create, delete, and list users across realms
- Realm Administration: Comprehensive realm management capabilities
- Secure Integration: Authentication with admin credentials
- Easy Configuration: Simple setup with environment variables
- LLM Integration: Seamless use with Claude, ChatGPT, and other MCP-compatible AI assistants

The server is available as an NPM package:

# Direct usage with npx npx -y @octodet/keycloak-mcp # Or global installation npm install -g @octodet/keycloak-mcp

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

Configure in your Claude Desktop configuration file:

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

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.

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

- 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

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

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

{ "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.

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

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

{ "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.

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

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

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

Retrieves all available realms in the Keycloak instance.

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

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

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

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

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

{ "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.

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

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

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

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

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

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

User IDs vs Usernames: Most operations require user IDs (UUIDs), not usernames. Uselist-usersto find the correct user ID.

Client Identification: TheclientIdparameter accepts both human-readable client IDs and UUID identifiers.

Realm Validation: Always verify realm names usinglist-realmsbefore performing operations.

Role Discovery: Uselist-rolesto discover available roles before attempting role assignments.

Error Handling: All tools provide detailed error messages for troubleshooting authentication, permission, or parameter issues.

# Clone the repository git clone <repository-url> # Install dependencies npm install # Start the development server with watch mode npm run watch

- Define the tool schema insrc/index.tsusing Zod
- Add the tool definition to theListToolsRequestSchemahandler
- Implement the tool handler in theCallToolRequestSchemaswitch statement
- Update this README to document the new tool

The MCP Inspector is a great tool for testing your MCP server:

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

For testing with a local Keycloak instance:

# 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

This project is published to NPM under@octodet/keycloak-mcp.

This project is licensed under the MIT License - see theLICENSEfile for details.

Task/project MCP server with OAuth for Claude, Cursor bridge, semantic search, staged write approval