KE
Developer Tools

Keycloak MCP Server for User and Realm Management

Manage Keycloak users and realms with the MCP server using natural language to create, delete, and list users and realms.

View on GitHub

Overview

This MCP (Model Context Protocol) server provides a bridge between language models and Keycloak, letting you manage realms and users using natural language. Instead of writing Keycloak Admin REST calls, you can prompt the server (or a connected model) with simple instructions like “create a realm named staging” or “add user alice in realm dev”. The server translates those intents into Keycloak operations and runs them with an admin account.

The server is useful for automation, admin scripting, and integrating Keycloak operations into LLM-driven workflows. It exposes an MCP-compatible interface and a set of typed tools for common Keycloak tasks, so you can plug it into conversational agents, automation pipelines, or command-line workflows while keeping access control and auditing on the Keycloak side.

Features

  • Natural-language-driven Keycloak management through MCP-compatible endpoints
  • Tools for creating, listing, updating, and deleting realms and users
  • Authentication with Keycloak admin credentials for safe operations
  • Simple HTTP endpoints and Docker-ready deployment
  • Tool metadata discovery so LLMs know what actions are available and their arguments
  • Audit-friendly operation (operations are explicit and map to Keycloak Admin REST)

Installation / Configuration

Requirements:

  • A running Keycloak instance with an admin account
  • Docker (recommended) or Node.js if running locally

Clone the repo and start with Docker:

git clone https://github.com/ChristophEnglisch/keycloak-model-context-protocol.git
cd keycloak-model-context-protocol
docker build -t keycloak-mcp .
docker run -it --rm \
  -e KEYCLOAK_URL="https://keycloak.example.com" \
  -e KEYCLOAK_REALM="master" \
  -e KEYCLOAK_CLIENT_ID="admin-cli" \
  -e KEYCLOAK_USERNAME="admin" \
  -e KEYCLOAK_PASSWORD="secret" \
  -p 8080:8080 \
  keycloak-mcp

Or use docker-compose (example):

version: "3.8"
services:
  keycloak-mcp:
    image: keycloak-mcp:latest
    build: .
    ports:
      - "8080:8080"
    environment:
      KEYCLOAK_URL: "https://keycloak.example.com"
      KEYCLOAK_REALM: "master"
      KEYCLOAK_CLIENT_ID: "admin-cli"
      KEYCLOAK_USERNAME: "admin"
      KEYCLOAK_PASSWORD: "secret"

Environment variables (typical):

  • KEYCLOAK_URL — Base URL of Keycloak (e.g. https://keycloak.example.com)
  • KEYCLOAK_REALM — Realm for admin authentication (often master)
  • KEYCLOAK_CLIENT_ID — Client id for admin auth (e.g. admin-cli)
  • KEYCLOAK_USERNAME — Keycloak admin username
  • KEYCLOAK_PASSWORD — Keycloak admin password
  • PORT — Port the MCP server listens on (default 8080)

If the project supports a local Node run, typical commands:

npm install
# configure .env with the env vars above
npm start

Available Tools

The server exposes a set of MCP-style tools for Keycloak management. Tools are discoverable via a metadata endpoint and are intended to be used by language model agents or HTTP clients.

Common tools (examples):

  • listRealms() — returns all realms
  • createRealm(name, options) — creates a realm with optional settings
  • deleteRealm(name) — removes a realm
  • listUsers(realm, filter?) — lists users in a realm, optional filter by username/email
  • createUser(realm, username, email, attributes?, password?) — creates a user and optionally sets a password
  • getUser(realm, userIdOrUsername) — retrieve user details
  • updateUser(realm, userId, updates) — update user attributes, email, enabled flag
  • deleteUser(realm, userIdOrUsername) — deletes a user
  • resetPassword(realm, userId, newPassword) — sets a new password for the user

You can discover tools and their signatures with the /tools or /mcp/tools endpoint (subject to the server’s path).

Use Cases

  1. Onboarding automation

    • Prompt: “Create a realm named staging and add user alice with email [email protected] and password P@ssw0rd”
    • Result: The server will call createRealm(“staging”) then createUser(“staging”, “alice”, “[email protected]”,…, password)

  2. Quick debugging or checks

    • Prompt: “List users in the dev realm whose email ends with @example.com”
    • Result: listUsers(“dev”, filter=“@example.com”) returns matching users for inspection

  3. ChatOps and runbooks

    • Integrate into Slack or a chat agent. Admins can request “delete the test realm ‘sandbox-42’” and the agent uses deleteRealm(“sandbox-42”) with a confirmation step.

  4. CI/CD and environment provisioning

    • In automated pipelines, create ephemeral realms and users for integration tests, then tear them down after tests complete.

Concrete example — curl to ask the MCP server:

curl -X POST http://localhost:8080/mcp/ask \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Create realm staging and user alice with email [email protected] and password P@ssw0rd"
  }'

Expected response (simplified):

{
  "actions": [
    { "tool": "createRealm", "args": { "name": "staging" } },
    { "tool": "createUser", "args": { "realm": "staging", "username": "alice", "email": "[email protected]", "password": "P@ssw0rd" } }
  ],
  "results": [
    { "status": "ok", "realmId": "staging" },
    { "status": "ok", "userId": "c3f..." }
  ]
}

This pattern makes operations explicit, auditable, and reversible.

Resources

  • GitHub: https://github.com/ChristophEnglisch/keycloak-model-context-protocol
  • Keycloak Admin REST API docs: https://www.keycloak.org/documentation
  • Model Context Protocol (MCP) concepts: use the server’s /tools metadata endpoint to integrate with LLM agents

Notes:

  • Always run with least-privilege admin credentials and secure the MCP server (TLS, auth) in production.
  • Test actions in a non-production Keycloak realm first to verify behavior and permissions.
Tags:developer-tools