An extensible MCP server for administering Keycloak with an AI assistant. Like Keycloak itself it is built around extension points: the tools, prompts, access checks, confirmations, audit sinks and system registries it ships are extensions, and your own come as a jar next to them (Extending).
Out of the box it covers users, groups, roles, clients, identity providers, organizations, authentication flows, events and realm settings: a comprehensive set of tools over the Admin REST API (after mcp-keycloak-admin), built with Quarkus for Keycloak 26.8, reached over streamable HTTP, and shaped so that small local models can use them too.
The intended setup is one shared MCP server per environment: one for dev, one for test, one for QA, one for production, each in front of the Keycloak systems of that environment (several installations, tenants, clusters) and their realms. Users log in to it through their MCP client, every Admin API call runs with their own roles, and policies, confirmations and audit sit in one place instead of on every laptop. The server itself holds no state: systems, keys, secrets, UI sessions, pending approvals and the audit trail live in a shared database (Database storage, PostgreSQL for several instances), so it can be deployed in a HA setup behind a load balancer; clients that still hold MCP sessions need it to route them back to the instance that opened them (Several instances). The same server also runs locally for a single administrator, which is where the quick start below begins.
- Several Keycloak systems per server. The systems of an environment are configured or registered at runtime,
each with its own signing key; the model names the system, or a client gets an MCP entry bound to one system or
realm. The
sharedprofile refuses to start without authentication and the other settings a server other people reach needs. - The user's own identity, or a service account. Users log in through their MCP client and consent to the server
acting for them. Every Admin API call then runs with a token Keycloak exchanges for theirs: it names both (
subthe user,actthe server's client), Keycloak enforces the user's roles, the server's own role scope caps what it may do, and Keycloak's events show who acted for whom. The token a user presents is never passed on to Keycloak, as the MCP specification demands. Destructive tools can be approved on the user's own device through CIBA. A service account is the alternative for a local or single-purpose setup. - Guardrails by default. Destructive tools need a confirmation, every call is audited with secrets redacted, roles the identity lacks hide the tools they would need, and allow-lists fence in realms, hosts and tools.
- Small models cope. By default the model sees three tools:
whoami,search_toolsandexecute_tool. It searches for what it needs ("kick a user" finds the logout tool), identifiers are forgiving (user by id or username, group by path), errors are structured and results compact. - Extensible. An SPI for your own tools, prompts, access checks, confirmers, audit sinks, system registries and stores, loaded from a jar; every extension is configured, ordered and switched off the same way, per server and, for access checks, per system and realm.
| standalone | fleet | |
|---|---|---|
| for | a developer, a local assistant, a team with one or two Keycloaks | an IAM team running several environments, installations and realms |
| shape | one process, MCP endpoint only | one internal admin instance (admin API, management UI) and any number of MCP instances behind a load balancer |
| systems | in the configuration (properties, env vars) | registered at runtime, signing keys created and rotated centrally |
| state | none, or an H2 file | PostgreSQL, a database user per side so MCP instances cannot change what the admin side configured |
| start with | the quick start below | Scenario 6, examples/split-deployment/, Several instances, Threat model |
Both run the same server with the same tools, guardrails and audit. The fleet shape adds central management on top, so a standalone setup can grow into it without a different product.
The shortest path is local, in the shape the server is meant for: one Keycloak, the server on your machine, and you logging in through your MCP client, so every call runs with your own roles. Needs Java 21 and Docker.
-
Start the demo Keycloak (realm
demowith users, groups, the public clientmcp-consumerthat MCP clients log in with and the server's own clientkeycloak-mcp):cd examples/run-modes && docker compose up -d --wait && cd ../..
-
Run the server with the user's own login. Its client holds no admin role: every Admin API call is made with a delegated token that Keycloak issues for the person who logged in and the server's client together, so Keycloak enforces that person's roles and its events name both. The token the MCP client presents only opens the MCP server and is never passed on, as the MCP specification demands. Keycloak has to be up first, the server reads the realm's discovery document at startup.
examples/run-modes/server.sh user-login # MCP endpoint: http://localhost:8081/mcpThe delegated token is Keycloak's token exchange delegation, a preview feature of Keycloak 26.8 that the demo stack switches on (what it needs).
-
Connect an MCP client and log in. The browser opens on connect; log in as
alice / alice-demo(realm admin) orcarol / carol-demo(may only view) and confirm thatkeycloak-mcpmay act on your behalf.- LM Studio: add
examples/run-modes/mcp-oauth.jsonto its MCP settings:{ "mcpServers": { "keycloak": { "url": "http://localhost:8081/mcp", "auth": { "CLIENT_ID": "mcp-consumer" } } } } - Claude Code:
claude mcp add --transport http --client-id mcp-consumer --callback-port 33418 keycloak http://localhost:8081/mcp, then/mcpinside a session starts the login - VS Code with GitHub Copilot: add the server to
.vscode/mcp.json(or the user profile'smcp.json):Start it from the file or the MCP: List Servers command. Keycloak refuses VS Code's dynamic client registration, so VS Code then asks for a client ID: enter{ "servers": { "keycloak": { "type": "http", "url": "http://localhost:8081/mcp" } } }mcp-consumerand leave the secret empty. Use the tools from the chat in Agent mode. - Cursor, Codex, Claude Desktop: Integrations
- LM Studio: add
-
Ask it something: "who am I" lists your roles with readable labels, "find users named ali", "which groups is alice in"; "disable bob" works as alice and comes back
forbiddenas carol, naming the role she lacks.
A service account instead of the login, for a client without OAuth or a single-purpose setup, is one env file away:
examples/run-modes/env/realm-admin.env with the plain examples/run-modes/mcp.json. The other access levels (full
admin, realm manager, read-only, two systems, private_key_jwt) are in examples/run-modes.
Without a build: the releases carry a
keycloak-mcp-server-<version>.tar.gz and .zip. Unpack, edit conf/kcmcp.conf or copy a ready-made setup from
the templates in conf/scenarios/, and start with bin/kcmcp.sh start (bin\kcmcp.bat on Windows); the archive's
README explains the layout. ./mvnw package -Pdist builds the same archives into modules/distribution/target/.
For a shared server per environment, start from examples/run-modes/env/shared.env (users log in, profile shared) and read
Security for what the profile requires, Several Keycloak systems for adding
systems and per-system entries, and multi-tenant or dynamic-systems
for a complete stack.
- The model's view.
tools/listdepends on the exposure mode:hybrid(default) listssearch_tools,execute_tool,whoamiand a few hot tools;directlists every tool.whoamitells the model who it acts as and which tools that unlocks. Tools - One pipeline for every call. Access policy, argument validation, realm check, confirmation, the handler, audit.
Errors are structured (
unknown_tool,invalid_arguments,forbidden,confirmation_required, ...) and say what to do next. Tools, Security - Keycloak's roles are the boundary. The server acts with a service account, or with a delegated token Keycloak
issues for the signed-in user and the server's client together (
exchange, Keycloak's token exchange delegation). A caller's own token is never passed on to Keycloak. Therealm-managementroles of that identity decide what works, server flags only narrow further. Security, delegated-auth - Destructive tools ask first. Through the client's elicitation, a
confirm: trueflag (local profile), an ownConfirmersuch as a ticket check, or CIBA on the user's device. CIBA confirmation
| page | what it covers |
|---|---|
| Architecture | the server's two instance roles in one picture: the MCP instance for clients and models, the admin instance for configuration, one database between them |
| Identity providers, authorization servers and Keycloak systems | the three kinds of parties the server deals with and its part towards each: relying party, resource server, client |
| Scenarios in pictures | diagrams of the ways the server runs: service account, user login, delegated agent, several systems, a shared deployment, registration, CIBA, read-only troubleshooting, the call pipeline |
| Tools | what the model sees, the tool areas, prompts |
| Integrations | adding the server to LM Studio, Claude Code, Claude Desktop, VS Code and Copilot, Cursor, Codex; the login's Keycloak side |
| Security | guardrails, profiles local and shared, access levels, per-tool checks, policies, callers and delegation, threat model and revocation |
| Configuration | every property with default and meaning |
| HTTPS and trusted certificates | HTTPS for the server, a Keycloak behind a private CA |
| Several Keycloak systems | static and dynamic systems, per-system keys, the admin API, one MCP entry per system or realm |
| Database storage | H2 or PostgreSQL for systems, keys, secrets, audit and sessions; encryption and key rotation |
| Management UI | the browser UI and its backend-for-frontend; work in progress, a login skeleton today |
| CIBA confirmation | approval of destructive tools on the user's device |
| Metrics | OpenTelemetry metrics and what they answer |
| Extending | the extension SPI: tools, prompts, checks, confirmers, audit listeners, extension jars |
| Supported Keycloak versions | baseline, feature and version requirements, OpenAPI alignment |
| Development | build, test, modules, formatting, roadmap |
Runnable setups, from a first demo realm to several tenants, delegation and CIBA: examples. Start with run-modes.
./mvnw test # unit + in-process MCP tests, no Keycloak
./mvnw verify -DskipITs=false # + integration tests against Keycloak 26.8.2 in Docker
./mvnw spotless:apply # format; `verify` fails on unformatted code
conformance/run.sh # MCP conformance suite against the packaged serverModules: api (extension SPI, no Quarkus), storage (database), backend (the Quarkus application and Lit
management UI), distribution (the downloadable archives). More in Development, including the
roadmap.