# keycloak-model-context-protocol

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 47 repo stars
- Author: ChristophEnglisch
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ChristophEnglisch/keycloak-model-context-protocol
- Updated: 2026-10-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/keycloak-model-context-protocol

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `KEYCLOAK_URL`, `KEYCLOAK_AUTH_REALM`, `KEYCLOAK_CLIENT_ID`, `KEYCLOAK_CLIENT_SECRET`, `KEYCLOAK_USERNAME`, `KEYCLOAK_PASSWORD`, `KEYCLOAK_GRANT_TYPE`, `KEYCLOAK_MCP_READ_ONLY`, `KEYCLOAK_MCP_REALMS`, `KEYCLOAK_MCP_ALLOW_MASTER_WRITE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-protocol
```
Replace <…> with your own values. 9 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
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-protocol
```
Replace <…> with your own values. 9 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-protocol
```
Replace <…> with your own values. 9 more environment variables are in the server README

## When to use it
- 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
- List the first users in realm `demo`.
- Show the groups in realm `demo`.
- List the realms I can access in Keycloak.

## Similar
- [keycloak-administration](https://affpapa.org/en/nevibecode/skills/keycloak-administration.md) — skill · 336 installs
- [keycloak-expert](https://affpapa.org/en/nevibecode/agents/keycloak-expert.md) — subagent · ★ 1029 repo stars
- [Phase Two Keycloak](https://affpapa.org/en/nevibecode/mcp/phase-two-keycloak.md) — MCP server · ★ 5 repo stars
- [model-context-protocol](https://affpapa.org/en/nevibecode/plugins/model-context-protocol.md) — plugin · ★ 2858 repo stars
- [model-context-protocol-mcp-expert](https://affpapa.org/en/nevibecode/plugins/model-context-protocol-mcp-expert.md) — plugin · ★ 1013 repo stars
- [Skycloak](https://affpapa.org/en/nevibecode/mcp/skycloak.md) — MCP server · ★ 1 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
