Keycloak MCP Server

Implements the Model Context Protocol (MCP) specification over Server-Sent Events (SSE) transport, accepting HTTP requests at /mcp/sse endpoint with JWT bearer tokens. The server validates each JWT against the Keycloak instance, extracts user identity and permissions, then proxies authenticated requests to Keycloak's Admin API using the user's own token rather than a shared service account. This zero-authorization proxy design delegates all permission enforcement to Keycloak itself, eliminating authorization bypass vulnerabilities.

Exposes 40+ Keycloak Admin API operations through MCP tools, with dedicated service layer for user management including create, read, update, delete, and search operations. The UserService class implements domain-specific user operations that are marshaled through KeycloakTool and exposed as callable MCP tools. Each operation constructs authenticated Keycloak client instances via KeycloakClientFactory using the request's JWT token, ensuring operations execute with the user's actual Keycloak permissions.

Provides Quarkus-based native binary compilation enabling deployment as standalone executables without JVM, with Docker container images and Kubernetes/OpenShift manifests for orchestrated deployment. The build system generates native binaries with GraalVM, producing executables with sub-second startup time and minimal memory footprint (~50-100MB vs 300-500MB for JVM). Includes pre-built container images and deployment configurations for Docker, Kubernetes, and OpenShift environments.

Implements stateless architecture using Quarkus request-scoped dependency injection, where each HTTP request receives isolated service instances and authenticated Keycloak client. The architecture eliminates shared state across requests, preventing credential leakage and ensuring request isolation. Request-scoped beans are instantiated per request and garbage collected after response, providing automatic resource cleanup and preventing memory leaks from accumulated client connections.

Exposes Keycloak realm-level operations through dedicated RealmService class, enabling creation, configuration, and management of realms as isolated security domains. The service layer abstracts realm operations including realm creation with default settings, theme configuration, security policy updates, and realm deletion. Each realm operation is authenticated using the request's JWT token and executed against the Keycloak Admin API with the user's actual permissions.

Exposes Keycloak client (OAuth2/OIDC application) management through dedicated ClientService, enabling creation, configuration, and lifecycle management of client applications. The service handles client creation with protocol-specific settings (OpenID Connect, SAML, etc.), credential generation, redirect URI configuration, and scope/role assignment. Each client operation uses the request's JWT token to authenticate against Keycloak Admin API, ensuring operations respect the user's actual permissions.

Exposes Keycloak role management through dedicated RoleService, enabling creation of realm-level and client-level roles, role hierarchy definition, and role assignment to users and groups. The service abstracts role operations including role creation with descriptions, composite role definition (roles containing other roles), and role-to-user/group mappings. Each role operation uses the request's JWT token to authenticate against Keycloak Admin API with the user's actual permissions.

Exposes Keycloak group management through dedicated GroupService, enabling creation of hierarchical user groups, group membership management, and group-level role assignment. The service handles group creation with parent-child relationships, user membership operations, and role inheritance through group membership. Each group operation uses the request's JWT token to authenticate against Keycloak Admin API with the user's actual permissions.

Exposes Keycloak identity provider management through dedicated IDPService, enabling configuration of external identity providers (SAML, OpenID Connect, social providers) for user federation and social login. The service handles IDP creation with protocol-specific settings, mapper configuration for attribute transformation, and IDP-to-realm linking. Each IDP operation uses the request's JWT token to authenticate against Keycloak Admin API with the user's actual permissions.

Exposes Keycloak authentication flow management through dedicated AuthenticationService, enabling creation and configuration of custom authentication flows, execution policies, and authentication requirements. The service handles flow creation with execution steps (password, OTP, WebAuthn, etc.), conditional execution policies, and flow binding to realms or clients. Each authentication operation uses the request's JWT token to authenticate against Keycloak Admin API with the user's actual permissions.

Implements KeycloakTool class that marshals 40+ Keycloak Admin API operations into discrete MCP tool definitions with standardized input/output schemas, error handling, and response transformation. The tool layer accepts MCP tool invocation requests, validates parameters against operation schemas, invokes corresponding service methods, and transforms responses into MCP-compatible format. Implements comprehensive error handling that catches Keycloak API errors and transforms them into human-readable MCP error responses.

Implements KeycloakClientFactory that creates request-scoped authenticated Keycloak client instances using JWT tokens from HTTP Authorization headers. The factory validates JWT tokens against the Keycloak instance, extracts user identity and realm information, and instantiates Keycloak Admin API clients with the user's credentials. Each request receives its own client instance ensuring isolation and preventing credential leakage across requests. The authentication system delegates all permission enforcement to Keycloak itself — the proxy contains zero authorization logic.