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.

Related MCP server: mcp-keycloak-admin

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

Use with your MCP client

Works with Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code (Copilot), and any other MCP client — see docs/CLIENTS.md for per-client setup.

Install

npm install
npm run build

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 with Claude Desktop / Claude Code

Add to your MCP client configuration (claude_desktop_config.json or via claude mcp add):

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-keycloak/dist/index.js"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only",
        "KEYCLOAK_REALM_ALLOWLIST": "app,customers"
      }
    }
  }
}

Bump KEYCLOAK_MODE to read-write (and, for deletes, admin + KEYCLOAK_ALLOW_DELETE=true) only when you intend to let the model make changes.

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 for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.

License

MIT