MCP Keycloak

mcp-keycloak

A Model Context Protocol server for Keycloak. It lets an MCP-capable client (Claude Desktop, Claude Code, etc.) inspect and manage Keycloak realms, users, clients, roles, and groups — with security controlled entirely by flags.

The design goal is safe by default: it starts read-only, scopes to an allowlist of realms, protects sensitive realms from mutation, and gates destructive operations behind an explicit opt-in.

Features

• Multi-realm — every tool takes a realm argument; scope it with an allowlist.
• Access modes — read-only → read-write → admin, layered so a mode never exposes tools above its level.
• Security flags — realm allowlist, protected realms, delete gating, dry-run, and JSON audit logging (see below).
• Two auth strategies — confidential-client service account (recommended) or admin username/password.
• Zero heavy dependencies — a thin fetch-based Admin REST client, plus the MCP SDK and zod.

Security model

These layers are independent — for example admin mode with KEYCLOAK_ALLOW_DELETE=false can create and update users but cannot delete them.

Tools

Read (read-only+): list_realms, get_realm, list_users, get_user, count_users, list_clients, list_realm_roles, list_groups

Write (read-write+): create_user, update_user, reset_password, logout_user

Admin (admin): delete_user

Quickstart — add to your agent

Published on npm as @dockndevai/mcp-keycloak. No clone or build needed — your MCP client runs it on demand with npx. Start in `read-only` mode; see .env.example for every variable and docs/CLIENTS.md for the full per-client guide.

Claude Code (CLI)

claude mcp add keycloak -e KEYCLOAK_URL="https://keycloak.example.com" -e KEYCLOAK_CLIENT_ID="admin-cli" -e KEYCLOAK_CLIENT_SECRET="your-secret" -e KEYCLOAK_MODE="read-only" -- npx -y @dockndevai/mcp-keycloak

Claude Desktop · Cursor · Windsurf — same block in claude_desktop_config.json, .cursor/mcp.json, or ~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "keycloak": { "command": "npx", "args": [ "-y", "@dockndevai/mcp-keycloak" ], "env": { "KEYCLOAK_URL": "https://keycloak.example.com", "KEYCLOAK_CLIENT_ID": "admin-cli", "KEYCLOAK_CLIENT_SECRET": "your-secret", "KEYCLOAK_MODE": "read-only" } } } }

OpenAI Codex CLI — in ~/.codex/config.toml:

[mcp_servers.keycloak]

command = "npx" args = ["-y", "@dockndevai/mcp-keycloak"] env = { KEYCLOAK_URL = "https://keycloak.example.com", KEYCLOAK_CLIENT_ID = "admin-cli", KEYCLOAK_CLIENT_SECRET = "your-secret", KEYCLOAK_MODE = "read-only" }

VS Code (GitHub Copilot, Agent mode) — in .vscode/mcp.json:

{

"servers": { "keycloak": { "type": "stdio", "command": "npx", "args": [ "-y", "@dockndevai/mcp-keycloak" ], "env": { "KEYCLOAK_URL": "https://keycloak.example.com", "KEYCLOAK_CLIENT_ID": "admin-cli", "KEYCLOAK_CLIENT_SECRET": "your-secret", "KEYCLOAK_MODE": "read-only" } } } }

Configure

Copy .env.example and fill it in, or set the variables directly in your MCP client config. A confidential client with the realm-management roles you need is the recommended credential.

Run from source (development)

Prefer the published package above. To run from a clone:

npm install

npm run build node dist/index.js # with the environment variables set

Develop

npm run dev        # watch mode

npm test # unit tests for the security policy npm run typecheck

Publishing

This server ships a server.json for the official MCP registry and an mcpName for npm ownership validation. See [PUBLISHING.md](PUBLISHING.md) for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.

License

MIT