Keycloak MCP Server

An MCP (Model Context Protocol) server that exposes Keycloak admin operations as tools. It runs over stdio and is launched by an MCP client (Claude Desktop, Claude Code, the MCP Inspector, etc.).

Built on @modelcontextprotocol/sdk and @keycloak/keycloak-admin-client.

---

Table of Contents

• How it works
• Requirements
• Environment variables
• Keycloak setup (service account)
• Install & run
• Integrate with Claude
  • Claude Code (CLI)
  • Claude Desktop
  • MCP Inspector
• Tools reference
• Usage tips
• Troubleshooting

---

How it works

• The server authenticates to Keycloak using the client_credentials grant (a service account) — no username/password required.
• A single shared KeycloakAdminClient is kept alive with lazy token management: the token is re-fetched only when it is within ~10s of expiry.
• Every tool takes a realm argument identifying which realm the operation targets. This is distinct from KEYCLOAK_REALM, which is only the realm used to authenticate the admin service account.
• Users are addressed by username, clients by clientId, groups by path or name, and roles by name — no UUIDs required in tool arguments.
• All diagnostic logging goes to stderr; stdout is reserved for the MCP protocol.

---

Requirements

• Node.js 18+ (Node 22 recommended)
• A running Keycloak instance (v26.x tested)
• A confidential client with a service account that has admin roles (see below)

---

Environment variables

Loaded from a .env file at the project root.

Variable	Required	Default	Description
KEYCLOAK_BASE_URL	no	http://localhost:8080	Base URL of the Keycloak server.
KEYCLOAK_REALM	no	master	Realm used for admin authentication (where the service-account client lives). Not the target realm of operations.
KEYCLOAK_CLIENT_ID	yes	—	The confidential client's clientId used for the client_credentials grant.
KEYCLOAK_CLIENT_SECRET	yes	—	The service account client secret. Keep this out of version control.

Example .env:

KEYCLOAK_BASE_URL=http://localhost:8080
KEYCLOAK_REALM=master
KEYCLOAK_CLIENT_ID=keycloak-mcp
KEYCLOAK_CLIENT_SECRET=your-service-account-secret

⚠️ Add .env to .gitignore. The secret is a full admin credential.

---

Keycloak setup (service account)

1. In the realm that will authenticate the server (usually master), create a client (e.g. keycloak-mcp):
   • Client authentication: On (confidential)
   • Service accounts roles: Enabled
   • Standard/Direct-access flows can be off.
2. Copy the client secret from Credentials into KEYCLOAK_CLIENT_SECRET.
3. Grant the service account admin roles under Service account roles:
   • For full access: assign the admin role (or realm-admin from the realm-management client of each target realm).
   • For read-only usage: assign roles like view-users, view-clients, view-realm, query-users, query-clients.
   • Write tools (create/update/delete user, reset password, assign roles, group membership, send email, logout) additionally need manage-users and manage-clients.
   • Realm-level writes (set-realm-enabled, create-realm-role, delete-realm-role, create-group, delete-group) need manage-realm.
   • impersonate-user needs the impersonation role. create-client / regenerate-client-secret need manage-clients.

---

Install & run

npm install

npm run dev       # Run the server over stdio, loading .env
npm run inspect   # Launch the MCP Inspector against the server for interactive testing

npm run dev runs the TypeScript entry point directly via tsx --env-file=.env src/index.ts. There is no separate build step.

---

Integrate with Claude

Claude Code (CLI)

The simplest, self-contained registration points the project's local tsx binary at the entry file and loads secrets from .env (so no secrets appear on the command line):

# From the project root
P="$(pwd)"
claude mcp add keycloak --scope user -- \
  "$P/node_modules/.bin/tsx" --env-file="$P/.env" "$P/src/index.ts"

Verify it connected:

claude mcp list
# keycloak: .../tsx --env-file=.../.env .../src/index.ts - ✔ Connected

Prefer passing env vars explicitly instead of an .env file? Use --env flags:

P="$(pwd)"
claude mcp add keycloak --scope user \
  --env KEYCLOAK_BASE_URL=http://localhost:8080 \
  --env KEYCLOAK_REALM=master \
  --env KEYCLOAK_CLIENT_ID=keycloak-mcp \
  --env KEYCLOAK_CLIENT_SECRET=your-service-account-secret \
  -- "$P/node_modules/.bin/tsx" "$P/src/index.ts"

To remove it later: claude mcp remove keycloak.

Claude Desktop

Edit the MCP config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a keycloak entry under mcpServers (use absolute paths):

{
  "mcpServers": {
    "keycloak": {
      "command": "/absolute/path/to/keycloak-mcp/node_modules/.bin/tsx",
      "args": [
        "--env-file=/absolute/path/to/keycloak-mcp/.env",
        "/absolute/path/to/keycloak-mcp/src/index.ts"
      ]
    }
  }
}

Or pass credentials inline via env instead of --env-file:

{
  "mcpServers": {
    "keycloak": {
      "command": "/absolute/path/to/keycloak-mcp/node_modules/.bin/tsx",
      "args": ["/absolute/path/to/keycloak-mcp/src/index.ts"],
      "env": {
        "KEYCLOAK_BASE_URL": "http://localhost:8080",
        "KEYCLOAK_REALM": "master",
        "KEYCLOAK_CLIENT_ID": "keycloak-mcp",
        "KEYCLOAK_CLIENT_SECRET": "your-service-account-secret"
      }
    }
  }
}

Restart Claude Desktop. The Keycloak tools then appear in the tools (🔨) menu.

MCP Inspector

npm run inspect

Opens the Inspector UI where you can browse and invoke each tool interactively.

---

Tools reference

All tools take a realm argument (the target realm) unless noted. Identifiers are human-readable: users by username, clients by clientId, groups by path/name, roles by name. List tools support first/max pagination (default first=0, max=50, max 200).

Read — Users

Tool	Description	Arguments
list-users	List users (id, username, email, enabled, federation link).	realm, search?, first?, max?
get-user	Get a single user by username, with profile fields and attributes. Optionally include groups and realm roles.	realm, username, includeGroups?, includeRealmRoles?
count-users	Count users, optionally matching a search term. Handy before paginating.	realm, search?
list-user-groups	List the groups a user is a direct member of (id, name, path).	realm, username
list-user-roles	List a user's directly-assigned role mappings: realm roles plus client roles grouped by client.	realm, username
list-user-credentials	List a user's credential metadata (id, type, label, created date). No secret values.	realm, username
list-user-sessions	List a user's active sessions (start/last-access times, IP, clients used).	realm, username
search-users-by-attribute	Find users by a custom attribute key/value (exact match). Paginated.	realm, attribute, value, first?, max?

Read — Clients

Tool	Description	Arguments
list-clients	List clients (id, clientId, name, enabled, protocol, public flag). Filter by clientId; paginated.	realm, clientId?, first?, max?
get-client	Get one client by clientId (protocol, flow settings, redirect URIs, web origins). No secret.	realm, clientId
get-client-secret	Retrieve a confidential client's current secret. Sensitive — non-public clients only.	realm, clientId

Read — Groups

Tool	Description	Arguments
list-groups	List groups as a tree (id, name, path, nested subGroups). Search + paginate top-level groups.	realm, search?, first?, max?
list-group-members	List members of a group (by path or name): id, username, email, enabled.	realm, group, first?, max?

Read — Roles

Tool	Description	Arguments
list-realm-roles	List realm-level roles (id, name, description, composite flag). Search + paginate.	realm, search?, first?, max?
list-client-roles	List roles defined by a specific client (by clientId).	realm, clientId
list-users-with-realm-role	List users that have a given realm role assigned.	realm, roleName, first?, max?

Read — Realms

Tool	Description	Arguments
list-realms	List realms visible to the admin service account (id, realm, enabled). Needs realm-view.	(none)
get-realm	Get a realm's key settings: enabled, login flags, token/session lifespans, SMTP-configured.	realm

Write — Realms

Tool	Description	Arguments
set-realm-enabled	Enable or disable a realm. Disabling blocks all logins to it immediately.	realm, enabled

Write — Users

Tool	Description	Arguments
create-user	Create a user; returns the new id. Optional permanent initial password. Fails if username exists.	realm, username, email?, firstName?, lastName?, enabled? (def. true), emailVerified? (def. false), password?
update-user	Update profile fields of an existing user. Only supplied fields change; needs ≥1 field.	realm, username, email?, firstName?, lastName?, emailVerified?
set-user-enabled	Enable or disable an account. Disabling blocks login immediately.	realm, username, enabled
delete-user	Permanently delete a user. Irreversible — prefer set-user-enabled(false) for temporary blocks.	realm, username
reset-user-password	Set a new password. temporary=true forces a change at next login.	realm, username, password, temporary? (def. true)
send-user-actions-email	Email the user required actions (e.g. VERIFY_EMAIL, UPDATE_PASSWORD). Needs SMTP on the realm.	realm, username, actions[], lifespan? (seconds)
logout-user	Revoke all of a user's active sessions, forcing re-authentication everywhere.	realm, username
impersonate-user	Start an impersonation session via the admin account. Sensitive — returns session/redirect data.	realm, username

Write — Role mappings

Tool	Description	Arguments
assign-realm-role	Assign a realm role to a user. Idempotent.	realm, username, roleName
remove-realm-role	Remove a realm role from a user. Idempotent.	realm, username, roleName
assign-client-role	Assign a client-level role to a user. Idempotent.	realm, username, clientId, roleName
remove-client-role	Remove a client-level role from a user. Idempotent.	realm, username, clientId, roleName

Write — Roles

Tool	Description	Arguments
create-realm-role	Create a realm-level role. Fails if the name already exists.	realm, name, description?
delete-realm-role	Delete a realm role by name. Irreversible — unmaps it from every user and group.	realm, name

Write — Groups

Tool	Description	Arguments
add-user-to-group	Add a user to a group (by path or name). Idempotent.	realm, username, group
remove-user-from-group	Remove a user from a group (by path or name). Idempotent.	realm, username, group
create-group	Create a top-level group, or a nested child when a parent (path/name) is supplied.	realm, name, parent?
delete-group	Delete a group (by path or name), including its subgroups. Irreversible.	realm, group

Write — Clients

Tool	Description	Arguments
create-client	Register a new client. Defaults to confidential standard-flow; toggle public / service-account.	realm, clientId, name?, description?, publicClient? (def. false), standardFlowEnabled? (def. true), serviceAccountsEnabled? (def. false), redirectUris?, webOrigins?
regenerate-client-secret	Rotate a confidential client's secret and return the new value. Sensitive; old secret dies.	realm, clientId

---

Usage tips

Once integrated, you can prompt Claude in natural language, for example:

• “List the first 10 users in the financement-realm realm whose name contains dupont.”
• “Show details for user jdoe in financement-realm, including their groups and realm roles.”
• “Disable the account olduser in financement-realm.”
• “Assign the offline_access realm role to jdoe in financement-realm.”
• “Set jdoe's email to jdoe@example.com and mark it verified.”
• “Send jdoe a VERIFY_EMAIL and UPDATE_PASSWORD action email.”
• “Log jdoe out of all sessions in financement-realm.”
• “Create a billing-admin realm role and assign it to jdoe.”
• “Rotate the client secret for my-backend in financement-realm.”
• “Find all users in financement-realm with attribute department = finance.”

Claude will pick the matching tool and fill in the arguments.

⚠️ Destructive tools have no confirmation step. delete-user, delete-group, delete-realm-role, logout-user, set-realm-enabled(false) and regenerate-client-secret take effect immediately and cannot be undone.

---

Troubleshooting

Symptom	Likely cause / fix
Server won't connect in claude mcp list	Check absolute paths; run npm install so node_modules/.bin/tsx exists; run npm run dev manually to see stderr.
401/auth errors	Wrong KEYCLOAK_CLIENT_ID/SECRET, or the service account lacks admin roles.
Tool returns "not found"	Verify realm, username, clientId, or group are exact; identifiers are case-sensitive.
get-client-secret fails	Client is public (no secret) — only confidential clients have one.
send-user-actions-email fails	The target realm has no SMTP server configured.
403 on realm/role/group writes	Service account lacks manage-realm (or impersonation for impersonate-user) on the target realm.
Missing users/clients in list	Service account lacks view-users / view-clients for that realm.
Changes not visible in Claude Desktop	Fully restart the app after editing the config.