Keycloak Source

An MCP (Model Context Protocol) server that allows AI assistants to navigate and understand Keycloak source code locally. Built for developers creating Keycloak customizations — SPIs, Authenticators, Required Actions, Token Handlers, User Policies, and more.

Prerequisites

• Node.js 18+
• Keycloak source code cloned locally
• ripgrep (rg) recommended for fast search — falls back to grep if not installed

Installation

Quick Start with npx

No installation needed — just configure your MCP client:

{
  "mcpServers": {
    "keycloak-source": {
      "command": "npx",
      "args": ["-y", "keycloak-source-mcp"],
      "env": {
        "KEYCLOAK_SOURCE_PATH": "/absolute/path/to/your/keycloak/source"
      }
    }
  }
}

Clone Keycloak Source

git clone https://github.com/keycloak/keycloak.git

Install ripgrep (recommended)

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Windows
choco install ripgrep

Configuration

Set the KEYCLOAK_SOURCE_PATH environment variable to point to your local Keycloak source checkout:

export KEYCLOAK_SOURCE_PATH=/path/to/keycloak

Tools

The MCP server registers 19 tools. The primary entry point for most questions is explain_implementation — the rest are more targeted operations you'll typically reach for once you know what you're looking at.

get_class_source

Get the full source code of a Java class.

> get_class_source("services/src/main/java/org/keycloak/authentication/AuthenticationProcessor.java")

File: services/src/main/java/org/keycloak/authentication/AuthenticationProcessor.java
============================================================

package org.keycloak.authentication;
...

find_interface_implementors

Find all classes that implement a given interface or extend a given class.

> find_interface_implementors("Authenticator")

Implementors/subclasses of: "Authenticator"
  services/src/main/java/org/keycloak/authentication/authenticators/browser/UsernamePasswordForm.java:25
    public class UsernamePasswordForm extends AbstractUsernameFormAuthenticator implements Authenticator
  ...

search_spi_definitions

List SPI definitions from META-INF/services files.

> search_spi_definitions("Authenticator")

SPI Definitions (filter: "Authenticator")
============================================================
Found 2 SPI definition(s):

  SPI Interface: org.keycloak.authentication.AuthenticatorFactory
  File: services/src/main/resources/META-INF/services/org.keycloak.authentication.AuthenticatorFactory
  Implementations:
    - org.keycloak.authentication.authenticators.browser.UsernamePasswordFormFactory
    ...

grep_source

Full-text regex search across the entire codebase.

> grep_source("@AutoService", "*.java", 10)

Search results for: "@AutoService" (files: *.java)
  server-spi/src/main/java/org/keycloak/provider/Spi.java:3:import com.google.auto.service.AutoService;
  ...

explain_implementation

The primary tool for understanding Keycloak internals. Accepts natural language queries about features or specific class names. Orchestrates deep source analysis including class hierarchies, interface method signatures, SPI extension points, implementations, and dependencies.

Topic query — conceptual overview:

> explain_implementation("authentication flow")

Keycloak Implementation Analysis: "authentication flow"
============================================================

Key Classes
----------------------------------------
  AuthenticationProcessor
    File: services/src/main/java/org/keycloak/authentication/AuthenticationProcessor.java
    Processes authentication flow executions
    Key methods: authenticate, attachSession, ...

Main Interfaces
----------------------------------------
  Authenticator
    File: server-spi/src/main/java/org/keycloak/authentication/Authenticator.java
    An authenticator is responsible for authenticating a user in the context of an authentication flow.
    Methods:
      - void authenticate(AuthenticationFlowContext context) — Called to authenticate a user
      - void action(AuthenticationFlowContext context) — Called after a form action has been submitted
      - boolean requiresUser() — Does this authenticator require the user to already be identified?
      ...

Default Implementations
----------------------------------------
  UsernamePasswordForm implements Authenticator
    File: services/src/main/java/org/.../UsernamePasswordForm.java
    Username/password form authenticator implementation

SPI Extension Points
----------------------------------------
  META-INF service: org.keycloak.authentication.AuthenticatorFactory
    Registered providers:
      - org.keycloak.authentication.authenticators.browser.UsernamePasswordFormFactory
      ...

Class query — deep analysis of a specific class:

> explain_implementation("UsernamePasswordForm")

Deep Analysis: UsernamePasswordForm
============================================================

Overview
----------------------------------------
File: services/src/main/java/org/.../UsernamePasswordForm.java
Package: org.keycloak.authentication.authenticators
Extends: AbstractUsernameFormAuthenticator
Username/password form authenticator implementation.

Methods
----------------------------------------
  void authenticate(AuthenticationFlowContext context)
  void action(AuthenticationFlowContext context)
  ...

Interface / Superclass Hierarchy
----------------------------------------
  AbstractUsernameFormAuthenticator
    Abstract base class for authenticators that use a username form
    Implements: Authenticator
    Methods: validateUser, requiresUser, close

Known Implementors / Subclasses
----------------------------------------
  (none — this is a concrete class)

Keycloak Dependencies
----------------------------------------
  org.keycloak.authentication.AuthenticationFlowContext
  org.keycloak.models.KeycloakSession
  ...

Full Source
----------------------------------------
  (complete source code)

Advanced Tools

add_version_from_branch

Create a git worktree of a Keycloak release/X.Y branch and register it as a named version. Lets you support multiple versions from a single clone (shared .git) without re-cloning gigabytes per version.

• Inputs: versionName, branch, optionally baseRepoPath (defaults to KEYCLOAK_SOURCE_PATH), optionally worktreePath.
• Example prompt: "Set up Keycloak 24.0 as a new version from the release branch."

> add_version_from_branch(versionName="v24", branch="release/24.0")

The version is usable immediately. Add a matching KEYCLOAK_SOURCE_V24=<path> env var to persist across restarts.

compare_versions

Compare Keycloak source across two registered versions. One tool with two modes:

• target: "class" (default) — diff a specific class or interface. Shows added/removed/changed methods, package or hierarchy moves, import diffs.
• target: "spi_scan" — scan well-known SPI interfaces (or a custom list) for breaking changes, with each change labeled BREAKING or NON-BREAKING.

Inputs: fromVersion, toVersion, target, plus query (class mode) or interfaces (spi_scan mode).

Example prompts:

• "Compare AuthenticationProcessor between v24 and v26."
• "What SPI interfaces changed between Keycloak 24 and 26 that would affect my custom Authenticator?"

> compare_versions(fromVersion="v24", toVersion="v26", query="Authenticator")
> compare_versions(fromVersion="v24", toVersion="v26", target="spi_scan", interfaces=["Authenticator", "AuthenticatorFactory"])

trace_dependencies

Trace what a Keycloak class depends on and what depends on it — understand the blast radius.

• Inputs: className, direction (upstream/downstream/both), optionally depth
• Example prompt: "What does AuthenticationProcessor depend on, and what uses it?"

> trace_dependencies("AuthenticationProcessor", "both", 2)

keycloak_admin

Connect to a running Keycloak instance and perform administrative queries.

• Inputs: action (list_realms, list_flows, list_clients, list_providers, get_realm_settings), optionally realm
• Additional env vars: KEYCLOAK_ADMIN_URL, KEYCLOAK_ADMIN_USERNAME, KEYCLOAK_ADMIN_PASSWORD, optionally KEYCLOAK_ADMIN_REALM, KEYCLOAK_ADMIN_CLIENT_ID
• Example prompt: "Show me all authentication flows in the master realm of my running Keycloak."

> keycloak_admin("list_flows", "master")

upgrade_assistant

Analyze your custom SPI implementations and detect compatibility issues when upgrading Keycloak.

• Inputs: customSourcePath, targetKeycloakVersion, optionally currentKeycloakSourcePath
• Example prompt: "Check if my custom extensions in /projects/my-keycloak-spi are compatible with Keycloak 26."

> upgrade_assistant("/projects/my-keycloak-spi", "26.0.0")

visualize_auth_flow

Visualize a Keycloak authentication flow as a Mermaid flowchart diagram from a realm export or plain English description.

• Inputs: source (realm_export or description), realmExportPath, flowName, description
• Example prompt: "Visualize the browser authentication flow from my realm export at /tmp/realm-export.json"

> visualize_auth_flow("realm_export", "/tmp/realm-export.json", "browser")
> visualize_auth_flow("description", undefined, undefined, "First cookie SSO, then username/password (required), then OTP (conditional)")

check_security_advisories

Check Keycloak's GitHub security advisories for known CVEs affecting a specific version.

• Inputs: keycloakVersion, optionally severity (all/critical/high/medium/low)
• Example prompt: "Are there any critical CVEs affecting Keycloak 24.0.3?"

> check_security_advisories("24.0.3", "critical")

Live Development Intelligence

Connect to a locally running Keycloak instance for real-time development assistance. Works with Docker, IDELauncher, or Maven — see what providers are loaded, trace authentication flows through logs, validate SPI registration, and inspect the running configuration.

Quick Setup

Start Keycloak (Docker is the simplest option):

docker run -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Then set these env vars in your MCP client config:

KC_DEV_URL=http://localhost:8080
KC_DEV_ADMIN_USERNAME=admin
KC_DEV_ADMIN_PASSWORD=admin
KC_DEV_LOG_PATH=/tmp/keycloak.log  # optional, enables log analysis

Then ask: "Use connect_dev_instance to check my Keycloak setup"

Live Dev Tools

Tool	Description
connect_dev_instance	Test connection, show version info and custom providers
get_loaded_providers	List all runtime SPI providers with source correlation
analyze_logs	Parse and analyze Keycloak log entries
trace_authentication_flow	Guide through tracing an auth flow with log analysis
validate_spi_registration	Check custom SPI setup for common mistakes
get_dev_instance_config	Show active configuration filtered by prefix
diagnose_user	Investigate why a user cannot log in — searches by name/email/username and checks account status, credentials, brute-force lockout, recent events, and sessions

Example Development Loop

You: "Check if my Keycloak is running and show custom providers" AI: 🟢 Keycloak 26.0.1 connected. 2 custom providers found — SmsSenderAuthenticatorFactory (✅ source found), AuditEventListener (⚠️ source not found)

You: "My SMS authenticator isn't working. Analyze the last 500 log lines" AI: Found 1 ERROR: AuthenticationFlowException at AuthenticationProcessor.java:456. Auth flow: cookie→skip, username-password→success, sms-auth→failure.

You: "Validate my SMS authenticator SPI registration" AI: ✅ Factory source found, ✅ META-INF/services entry present, ✅ Provider loaded at runtime. Registration looks correct — the issue is in the authenticator logic, not registration.

For comprehensive documentation, see docs/live-dev-intelligence.md.

Claude Desktop Configuration

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "keycloak-source": {
      "command": "npx",
      "args": ["-y", "keycloak-source-mcp"],
      "env": {
        "KEYCLOAK_SOURCE_PATH": "/absolute/path/to/your/keycloak/source"
      }
    }
  }
}

Example Conversations

"How does Keycloak handle authentication flows?" Use explain_implementation("authentication flow") — returns key classes, interface method signatures, default implementations, and SPI extension points in a single call.

"I want to build a custom Authenticator SPI" Use explain_implementation("Authenticator") to get the full interface contract with method javadocs, known implementors, and SPI registration. Then explain_implementation("UsernamePasswordForm") to study a concrete example with full source.

"Where is the token refresh logic?" Use explain_implementation("token refresh") to find the relevant classes, interfaces, and SPI extension points.

"Show me how Required Actions work" Use explain_implementation("required action") to discover key interfaces with method signatures, or explain_implementation("RequiredActionProvider") for a deep dive into the interface itself.

Development

npm install
npm run build
npm start

Roadmap

Potential future tools:

• Multi-realm diff across environments — Compare realm configurations between dev, staging, and production
• Automated upgrade PR generator — Generate a pull request with all needed changes to upgrade custom SPIs
• Keycloak Operator CRD assistant — Help build and validate custom resources for the Keycloak Operator
• Performance profiling hints based on SPI usage patterns — Detect common performance anti-patterns in custom implementations

License

MIT