Skip to content

keycloak-agent

Keycloak Identity and Access Management MCP Server + Agent for the scion-sdk ecosystem — typed, deterministic tools for realms, users, and OIDC clients, plus an optional Pydantic-AI agent server.

Official documentation

This site is the canonical reference for keycloak-agent, maintained alongside every release.

PyPI MCP Server License GitHub

Overview

keycloak-agent wraps the Keycloak Admin REST API with a typed, deterministic MCP tool surface and ships an optional agent server. It provides:

  • Api — a dynamic facade (keycloak_agent.api_client.Api) composed of realm, user, and OIDC-client domain modules over the Keycloak Admin REST API.
  • MCP tools — realm, user, and client operations registered under the KEY tag, with runtime toolset selection to keep the model's context window lean.
  • An agent server — an optional Pydantic-AI keycloak-agent that consumes the MCP tools for autonomous identity operations.

The server registers read operations that work as soon as the connection is configured; administrative writes ran only when valid credentials are present.

Explore the documentation

  • :material-rocket-start: Installation — pip, source, extras, and the prebuilt Docker image.
  • Deployment — run the MCP server and agent, Docker Compose, Caddy + Technitium.
  • Usage — the MCP tools, the Api client, and the CLI.
  • Backing Platform — deploy Keycloak with Docker.
  • Architecture — the dynamic facade and tool surface.
  • Concepts — the CONCEPT:KEY-* registry.

Quick start

pip install "keycloak-agent[mcp]"
keycloak-mcp                       # stdio MCP server (default transport)

Connect it to a Keycloak server:

export KEYCLOAK_URL=<configured-endpoint>
export KEYCLOAK_AGENT_USERNAME=<configured-principal>
export KEYCLOAK_AGENT_PASSWORD=<runtime-secret>
export KEYCLOAK_REALM=master
keycloak-mcp --transport streamable-http --host 0.0.0.0 --port 8000

See Installation and Deployment for the full matrix (PyPI extras, Docker image, all transports, the agent server, reverse proxy, DNS).

Spec delivery

Spec delivery dashboard. No owned specs are recorded yet. Missing requirement and code mappings remain unknown.