Keycloak Source MCP Server

keycloak-source-mcp

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

search_class

Search for a Java class or interface by name.

> search_class("AuthenticationProcessor")

Search results for class: "AuthenticationProcessor"
  services/src/main/java/org/keycloak/authentication/AuthenticationProcessor.java
    Package: org.keycloak.authentication
    public class AuthenticationProcessor {

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.authentica