keycloak-model-context-protocol — Claude Code MCP server setup
keycloak-model-context-protocol is an MCP server for Claude Code that connects an AI assistant to Keycloak administration of users, groups, roles, and realms.
MIT ★ 47 updated 2026-10-26
claude mcp add --env KEYCLOAK_URL=<KEYCLOAK_URL> --env KEYCLOAK_AUTH_REALM=<KEYCLOAK_AUTH_REALM> --env KEYCLOAK_CLIENT_ID=<KEYCLOAK_CLIENT_ID> --env KEYCLOAK_CLIENT_SECRET=<KEYCLOAK_CLIENT_SECRET> --env KEYCLOAK_USERNAME=<KEYCLOAK_USERNAME> --transport stdio keycloak-model-context-protocol -- npx -y keycloak-model-context-protocolWhat keycloak-model-context-protocol does
The server connects to Keycloak's Admin REST API. It lets an assistant manage users, groups, and roles, and inspect realms. Tools are enabled in sets; core, groups, and roles are active by default. You can also restrict the server to read-only access or limit it to an allowlist of realms.
You need Node.js 22 or newer, a Keycloak instance reachable from your machine, and an MCP client. Provide the Keycloak URL and login credentials. For client_credentials authentication, set up a service-account client and grant only the roles required for your tasks. Writes first return a preview and require confirmation by default. The connection cannot work if the Keycloak server is unreachable.
What it helps with
- inspect users in a chosen realm
- manage Keycloak groups
- assign roles to users
- restrict the server to read-only tools
- list realms available to the account
Example prompts for the agent
- List the first users in realm
demo. - Show the groups in realm
demo. - List the realms I can access in Keycloak.
How to install keycloak-model-context-protocol
Platform CLI
claude mcp add --env KEYCLOAK_URL=<KEYCLOAK_URL> --env KEYCLOAK_AUTH_REALM=<KEYCLOAK_AUTH_REALM> --env KEYCLOAK_CLIENT_ID=<KEYCLOAK_CLIENT_ID> --env KEYCLOAK_CLIENT_SECRET=<KEYCLOAK_CLIENT_SECRET> --env KEYCLOAK_USERNAME=<KEYCLOAK_USERNAME> --transport stdio keycloak-model-context-protocol -- npx -y keycloak-model-context-protocolReplace <…> with your own values. 9 more environment variables are in the server README
Platform CLI
codex mcp add keycloak-model-context-protocol --env KEYCLOAK_URL=<KEYCLOAK_URL> --env KEYCLOAK_AUTH_REALM=<KEYCLOAK_AUTH_REALM> --env KEYCLOAK_CLIENT_ID=<KEYCLOAK_CLIENT_ID> --env KEYCLOAK_CLIENT_SECRET=<KEYCLOAK_CLIENT_SECRET> --env KEYCLOAK_USERNAME=<KEYCLOAK_USERNAME> -- npx -y keycloak-model-context-protocolReplace <…> with your own values. 9 more environment variables are in the server README
Config file
{
"mcpServers": {
"keycloak-model-context-protocol": {
"command": "npx",
"args": [
"-y",
"keycloak-model-context-protocol"
],
"env": {
"KEYCLOAK_URL": "<KEYCLOAK_URL>",
"KEYCLOAK_AUTH_REALM": "<KEYCLOAK_AUTH_REALM>",
"KEYCLOAK_CLIENT_ID": "<KEYCLOAK_CLIENT_ID>",
"KEYCLOAK_CLIENT_SECRET": "<KEYCLOAK_CLIENT_SECRET>",
"KEYCLOAK_USERNAME": "<KEYCLOAK_USERNAME>"
}
}
}
}Replace <…> with your own values. 9 more environment variables are in the server README
Config file
{
"servers": {
"keycloak-model-context-protocol": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"keycloak-model-context-protocol"
],
"env": {
"KEYCLOAK_URL": "<KEYCLOAK_URL>",
"KEYCLOAK_AUTH_REALM": "<KEYCLOAK_AUTH_REALM>",
"KEYCLOAK_CLIENT_ID": "<KEYCLOAK_CLIENT_ID>",
"KEYCLOAK_CLIENT_SECRET": "<KEYCLOAK_CLIENT_SECRET>",
"KEYCLOAK_USERNAME": "<KEYCLOAK_USERNAME>"
}
}
}
}Replace <…> with your own values. 9 more environment variables are in the server README
Platform CLI
gemini mcp add -e KEYCLOAK_URL=<KEYCLOAK_URL> -e KEYCLOAK_AUTH_REALM=<KEYCLOAK_AUTH_REALM> -e KEYCLOAK_CLIENT_ID=<KEYCLOAK_CLIENT_ID> -e KEYCLOAK_CLIENT_SECRET=<KEYCLOAK_CLIENT_SECRET> -e KEYCLOAK_USERNAME=<KEYCLOAK_USERNAME> keycloak-model-context-protocol npx -y keycloak-model-context-protocolReplace <…> with your own values. 9 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about keycloak-model-context-protocol
How do I install keycloak-model-context-protocol in Claude Code?
Run `claude mcp add keycloak-model-context-protocol -e KEYCLOAK_URL=<KEYCLOAK_URL> -e KEYCLOAK_CLIENT_SECRET=<KEYCLOAK_CLIENT_SECRET> -e KEYCLOAK_PASSWORD=<KEYCLOAK_PASSWORD> -- npx -y keycloak-model-context-protocol`. Set the Keycloak URL and credentials for your chosen login method.
What does keycloak-model-context-protocol do?
It gives an AI assistant access to Keycloak's Admin REST API. The server can manage users, groups, and roles, and inspect realms.
What is required to run the Keycloak MCP server?
You need Node.js 22 or newer, a reachable Keycloak server, and an MCP client. With client_credentials, configure a service-account client and assign the roles the tasks require.