Keycloak MCP Server

MCP server for Keycloak Identity and Access Management instances. Auto-generates 401 tools from the Keycloak OpenAPI specification using FastMCP.from_openapi(). Includes CodeMode for efficient AI interaction with large tool sets, and supports dual authentication modes (OAuth2 HTTP transport for user sessions, client_credentials for stdio service accounts).

Configuration

Authentication: Keycloak supports two modes depending on transport:

• stdio (service account): Uses client_credentials or password grant to obtain tokens automatically
• HTTP (user OAuth): Uses OIDC proxy to authenticate end-users via browser flow

Option 1: config.json

cp config.json.example config.json
# Edit config.json with your Keycloak credentials

Option 2: Environment Variables

export KEYCLOAK_HOST="keycloak.example.com"
export KEYCLOAK_REALM="master"
export KEYCLOAK_CLIENT_ID="admin-cli"
export KEYCLOAK_CLIENT_SECRET="your-client-secret"
# Or use password grant:
export KEYCLOAK_USERNAME="admin"
export KEYCLOAK_PASSWORD="admin-password"
export KEYCLOAK_VERIFY_SSL="true"
export KEYCLOAK_CA_CERT_PATH=""
export KEYCLOAK_TIMEOUT="30"

Authentication Modes

stdio Mode (Service Account)

For AI assistants connecting via stdio transport. The server acquires tokens automatically using either:

• Client credentials grant: Set client_id + client_secret. Best for service-to-service.
• Password grant: Set username + password. Falls back to admin-cli as client_id.

Tokens are cached and refreshed automatically before expiry.

HTTP Mode (User OAuth Flow)

For web-based access where end-users authenticate via browser:

python -m bibliocommons_mcp_keycloak --transport http --port 8000

Uses OIDC proxy with your Keycloak realm's well-known configuration. Users authenticate through the standard Keycloak login page.

Installation

Option 1: Using uvx (Recommended — no install needed)

uvx bibliocommons-mcp-keycloak

uvx runs the package directly from PyPI in an isolated environment. Install uv first if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Option 2: Using pip

pip install bibliocommons-mcp-keycloak

AI Client Setup

VS Code (with MCP Extension)

{
  "mcp.servers": {
    "keycloak": {
      "command": "uvx",
      "args": ["bibliocommons-mcp-keycloak"]
    }
  }
}

Claude Desktop

Configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "keycloak": {
      "command": "uvx",
      "args": ["bibliocommons-mcp-keycloak"]
    }
  }
}

Kiro IDE

{
  "mcpServers": {
    "keycloak": {
      "command": "uvx",
      "args": ["bibliocommons-mcp-keycloak"]
    }
  }
}

Kiro CLI

Create or edit ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "uvx",
      "args": ["bibliocommons-mcp-keycloak"]
    }
  }
}

Configuration Notes

• Add --config /path/to/config.json to the args array to use a specific config file
• Add --read-only to the args array to disable destructive tools
• After adding the configuration, restart your AI client for changes to take effect

For other AI clients (Amazon Q, GitHub Copilot, Cline, Zed, Cursor), see docs/ai-clients.md.

Docker

# Pull from Docker Hub (private)
docker pull bibliocommons/mcp-keycloak:latest

# Run in stdio mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-keycloak:latest \
  --config /config.json

# Run in HTTP mode
docker run -d --rm \
  -v /path/to/config.json:/config.json:ro \
  -p 8000:8000 \
  bibliocommons/mcp-keycloak:latest \
  --config /config.json --transport http --port 8000

# Run in expanded mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-keycloak:latest \
  --config /config.json --expanded

Standalone MCP Server

python -m bibliocommons_mcp_keycloak

CLI Flags

Gateway Mode (Default)

By default, the server exposes 2 tools instead of 401 individual tools:

The AI assistant calls keycloak_help to discover available actions, then calls keycloak_api(action="get_users", params={"realm": "master"}) to execute them.

To register all individual tools (previous behavior), use --expanded:

python -m bibliocommons_mcp_keycloak --expanded

Read-Only Mode

Disable all write operations (POST, PUT, DELETE, PATCH) for safe, audit-only operation:

# CLI flag
python -m bibliocommons_mcp_keycloak --read-only

# Environment variable
export KEYCLOAK_READ_ONLY=true

In read-only mode, only GET-based tools are exposed. All mutating operations are excluded.

OpenAPI Spec

A copy of the Keycloak OpenAPI spec (src/bibliocommons_mcp_keycloak/openapi.json) ships in the package, so the server starts without any download.

At startup it also asks keycloak.org whether a newer spec exists (5 second limit, conditional request, so an unchanged spec costs almost nothing). A newer spec is used straight away and kept in the user cache directory, ~/.cache/bibliocommons-mcp-keycloak/openapi.json ($XDG_CACHE_HOME is honoured). A cached spec is only used while it is newer than the bundled one, so upgrading the package is never undone by an old cache.

If the check fails (offline, a proxy, a timeout, an unexpected response) the server logs a warning and boots with the bundled or cached spec. It never fails to start because of it.

To refresh the bundled copy before a release, run make update-spec and commit the result.

Security Notes

• Create a dedicated service account in Keycloak for MCP access with minimal required roles
• Never commit config.json with real credentials (excluded by .gitignore)
• Use config.json.example as a template
• Prefer environment variables for production and CI environments
• Use --read-only mode when write access is not needed
• Tokens are cached in memory only and never written to disk
• Set verify_ssl=true in production; only disable for development with self-signed certificates