Keycloak MCP Server

An MCP (Model Context Protocol) server for the Keycloak Admin API, enabling AI models to manage Keycloak realms, users, clients, roles, and more.

Features

• User Management: Create, read, update, delete users, manage credentials, and list sessions.
• Client Management: Create and manage OIDC/SAML clients, including client secrets and scopes.
• Role & Group Management: Create and assign realm and client roles, manage group hierarchies.
• Realm Management: Configure realm settings, security browser headers, and themes.
• Identity Providers: Configure social and OIDC/SAML identity providers.
• Authentication: Manage authentication flows, executions, and requirements.
• Authorization: Fine-grained authorization resources, policies, and permissions.
• OAuth 2.1 Support: Built-in support for secure OAuth 2.1 resource server implementation.

Architecture

flowchart LR
    subgraph Client
        AI[AI Assistant]
    end
    subgraph MCP Server
        Auth[JWT Auth]
        MCP[MCP Protocol]
        Tools[150+ Tools]
        KC[Keycloak Client]
    end
    subgraph Keycloak
        API[Admin REST API]
        OIDC[OAuth/OIDC]
    end

    AI -->|MCP over HTTP| Auth
    Auth -->|Validate| OIDC
    Auth --> MCP --> Tools --> KC
    KC -->|HTTP| API

Loading

The server sits between AI assistants and Keycloak, translating MCP tool calls into Admin REST API requests. All requests are authenticated via JWT tokens validated against Keycloak's own OIDC endpoints, so the AI operates within the caller's security context.

For detailed architecture documentation, see Architecture.

Prerequisites

• Rust: 1.75 or later.
• Docker: For containerized deployment (optional).
• Keycloak: 26.0 or later (older versions may work but are not officially tested).

Quick Start

1. Configure the environment

Copy the .env.example to .env and update the values:

cp .env.example .env

Key required variables:

• KEYCLOAK_URL: Your Keycloak base URL (e.g., http://localhost:8080)
• KEYCLOAK_REALM: The realm to authenticate against (default: master)

2. Build and Run

cargo build --release
./target/release/keycloak-mcp-server

The server will start listening on the port specified by MCP_PORT (default: 3000).

Docker Deployment

You can run the server and Keycloak together using Docker Compose:

docker-compose up -d

This will start:

• Keycloak on port 8080
• Keycloak MCP Server on port 3000

Configuration Options

Variable	Description	Default
KEYCLOAK_URL	Base URL of Keycloak	http://localhost:8080
KEYCLOAK_REALM	Realm for Admin API access	master
MCP_PORT	Port for the MCP server	3000
LOG_LEVEL	Logging verbosity (trace/debug/info/warn/error)	info
JWKS_CACHE_TTL	JWKS cache time-to-live in seconds	3600

Keycloak Documentation Lookup

For Keycloak documentation queries, AI assistants can use WebSearch and WebFetch tool calls to look up the official Keycloak docs at keycloak.org directly. No local vector database needed — just search and fetch on demand.

API Coverage Summary

The server provides comprehensive coverage for Keycloak Admin REST API:

• Realms: Full CRUD and configuration.
• Users: Search, CRUD, password management, role mapping.
• Clients: CRUD, secrets, scopes, mappers.
• Roles: Realm and client level roles.
• Groups: Hierarchy management, member management.
• Authentication: Flows and executions.
• Identity Providers: Configuration and management.

Documentation

For detailed documentation, see the docs/ directory:

Document	Description
Overview	Project introduction and quick start guide
Architecture	System architecture with diagrams
Request Flow	Request lifecycle and authentication flow
Components	Detailed component documentation
API Reference	Complete tool reference (150+ tools)
Configuration	Environment variables and settings
Extending	Guide for adding new tools
Troubleshooting	Common issues and solutions

Development Setup

To run tests:

cargo test

To check for linting issues:

cargo clippy

To format code:

cargo fmt

License

This project is licensed under the MIT License - see the LICENSE file for details.