keycloak

The Keycloak MCP Server provides programmatic access to Keycloak administration via the Model Context Protocol (MCP). It enables AI assistants and development tools to manage users, realms, clients, roles, groups, and authentication flows through a standardized MCP interface backed by Keycloak's Admin Client. The server supports SSE (Server-Sent Events) transport for HTTP-based communication, and is designed for production-ready deployment in OpenShift or Kubernetes environments. To use it, run the server in a container (as shown in the quick start) and connect your MCP client to the SSE endpoint, providing a Bearer JWT token issued by Keycloak for authentication. Your MCP client can then issue requests to perform operations such as creating users, configuring realms, or managing clients and roles within Keycloak, all through the MCP abstraction.

Prerequisites:

• Docker (for container deployment) or a Java development environment if you prefer building from source
• Java JDK 11+ and Maven if building from source
• Access to a Keycloak instance for integration and authentication

Installation options:

1. Run via Docker (quick start):

   • Ensure Docker is installed and running
   • Start the MCP server container: docker run -d
     --name keycloak-mcp-server
     -p 8080:8080
     -e KC_URL=https://keycloak.example.com
     -e KC_REALM=master
     -e OIDC_CLIENT_ID=mcp-server
     quay.io/sshaaf/keycloak-mcp-server:latest

2. Build from source and run locally (optional):

   • mbt prerequisites installed (JDK and Maven)
   • Clone the repository and navigate to the project directory
   • Build: mvn clean package
   • Run the application (example using Quarkus jar): java -jar target/quarkus-app/quarkus-run.jar

3. Pull and run pre-built image (alternative container approach):

   • docker pull quay.io/sshaaf/keycloak-mcp-server:latest
   • docker run -d -p 8080:8080 quay.io/sshaaf/keycloak-mcp-server:latest

Prerequisite notes:

• The MCP server relies on Keycloak accessibility and proper network routing from the host or cluster where it runs.
• If you deploy to Kubernetes/OpenShift, configure the corresponding deployment descriptors and Secrets for KC_URL, KC_REALM, and client credentials.

Tips and common considerations:

• The server uses JWT tokens issued by Keycloak for authentication. Ensure your MCP client obtains a valid token and passes it in the Authorization header when connecting to the SSE endpoint.
• The default exposed port is 8080; adjust firewall and ingress rules accordingly when deploying behind load balancers.
• If you plan to run in production, consider configuring TLS termination at the ingress and avoiding expose of the internal port directly.
• For Kubernetes/OpenShift deployments, use the provided container image and apply the standard MCP deployment patterns and health checks.
• Review the docs folder (docs/index.md and related guides) for authentication, OpenShift deployment, and developers guide to customize behavior.
• When using the container image, environment variables (KC_URL, KC_REALM, OIDC_CLIENT_ID) should reflect your Keycloak deployment and OAuth client configuration.