Repository avatar
Security
v0.3.0
active

gocloak-mcp

io.github.Nerzal/gocloak-mcp

Security-first, read-only Keycloak MCP server built in Go with GoCloak v15.

Documentation

gocloak-mcp

CI Release Go GHCR License

A security-first, read-only Keycloak MCP server built in Go with the official MCP Go SDK and GoCloak v15. Supports Stdio (default) and Streamable HTTP transports, multi-realm allowlisting, and full read-only parity across Users, Clients, Client Scopes, Roles, Groups, Realms, Events, Authentication Flows, Required Actions, Identity Providers, and Keycloak 26+ Organizations.

In Stdio mode, standard output is strictly reserved for JSON-RPC frames and all structured JSON logs are written to standard error with automatic redaction.

Performance Benchmarks (v0.3.0)

gocloak-mcp v0.3.0 Head-to-Head Benchmarks

Measured head-to-head on ubuntu-latest (4 vCPU x86_64) against an identical local mock Keycloak Admin API (50 users/call). See Security & Benchmarks for the full OWASP MCP Top 10 control matrix, pprof optimization progression, and reproducible harness (benchmarks/run_benchmarks.py):

ServerTransportBinary / ImageCold StartRSS (Load)Throughput
gocloak-mcp (v0.3.0, Go 1.27 + gocloak v15.1)Stdio / HTTP10.2 MB / 21.1 MB9.9 ms / 22.7 ms16.2 MB / 17.4 MB1,227 / 1,140 req/s
MnemoShare/mnemoshare-keycloak-mcp (Go)Stdio / HTTP10.4 MB20.0 ms / 21.7 ms17.4 MB / 18.5 MB1,161 / 1,120 req/s
HaithamOumerzoug/keycloak-mcp (TS/Node 22)StdioNode runtime114.1 ms97.6 MB480 req/s
idoyudha/mcp-keycloak (Python 3.12 / FastMCP)StdioPython venv591.4 ms64.1 MB145 req/s
sshaaf/keycloak-mcp-server (Quarkus Native)HTTP74.1 MB63.5 ms151.4 MB205 req/s
sshaaf/keycloak-mcp-server (Quarkus JVM)HTTP23.4 MB JAR / 626 MB2,024.1 ms310.8 MB158 req/s

Requirements

  • Go 1.27.4 or newer
  • A Keycloak confidential client with service accounts enabled
  • A client secret supplied through the environment

Configuration

The server validates configuration before it starts and exits without printing secrets when validation fails.

Environment variableRequiredDefaultDescription
KEYCLOAK_URLYes—HTTPS Keycloak base URL (a /auth prefix is allowed); loopback HTTP is allowed for local development
KEYCLOAK_REALMYes—Default target realm and token-issuing realm
KEYCLOAK_ALLOWED_REALMSNoKEYCLOAK_REALMComma-separated allowlist of realms tools may query (KEYCLOAK_REALM is always included)
KEYCLOAK_CLIENT_IDYes—Service-account client ID
KEYCLOAK_CLIENT_SECRETYes—Service-account client secret
KEYCLOAK_REQUEST_TIMEOUTNo15sPer-request timeout; valid range is > 0 and <= 2m
MCP_TRANSPORTNostdioTransport mode: stdio or http (Streamable HTTP)
MCP_HTTP_ADDRNo127.0.0.1:8080Listen address when MCP_TRANSPORT=http
MCP_HTTP_BEARER_TOKENConditional—Optional on loopback; required (min 32 chars) when MCP_HTTP_ADDR binds to a non-loopback address
MCP_HTTP_ALLOWED_ORIGINSNoLoopback onlyComma-separated additional Origin allowlist for browser clients on Streamable HTTP (DNS rebinding protection)

Use your deployment platform's secret manager to provide secrets. Do not put credentials in command-line arguments, configuration files, or logs.

Minimal Keycloak permissions

Create a dedicated confidential client with service accounts enabled and assign only the read-only realm-management roles required for the tools you use:

  • query-users, view-users — user, session, and group-membership tools
  • query-clients, view-clients — client, client-role, and client-scope tools
  • query-groups — group tools
  • view-realm — realm, role, auth-flow, required-action, and IdP tools
  • view-events — login and admin event tools

Do not use the master realm or grant realm-admin unless explicitly required.

Installation

Homebrew (macOS & Linux)

brew install --cask nerzal/tap/gocloak-mcp

Prebuilt binaries (GitHub Releases)

Download the archive for your platform (darwin, linux, windows for amd64 and arm64) from the GitHub Releases page, verify the SHA-256 checksum against checksums.txt, and place gocloak-mcp on your PATH.

Docker / GHCR (multi-arch: linux/amd64, linux/arm64)

docker pull ghcr.io/nerzal/gocloak-mcp:latest

The image contains a static binary on gcr.io/distroless/static-debian12:nonroot.

Go install (from source)

go install github.com/Nerzal/gocloak-mcp/cmd/gocloak-mcp@latest

MCP client configuration

Native binary (Stdio)

Works with Claude Desktop, Cursor, VS Code, Claude Code, and other Stdio MCP clients:

{
  "mcpServers": {
    "keycloak": {
      "command": "gocloak-mcp",
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_REALM": "example",
        "KEYCLOAK_CLIENT_ID": "gocloak-mcp",
        "KEYCLOAK_CLIENT_SECRET": "<injected by your secret manager>"
      }
    }
  }
}

Docker container (Stdio)

Run isolated without installing a local binary:

{
  "mcpServers": {
    "keycloak": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "KEYCLOAK_URL",
        "-e", "KEYCLOAK_REALM",
        "-e", "KEYCLOAK_CLIENT_ID",
        "-e", "KEYCLOAK_CLIENT_SECRET",
        "ghcr.io/nerzal/gocloak-mcp:latest"
      ],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_REALM": "example",
        "KEYCLOAK_CLIENT_ID": "gocloak-mcp",
        "KEYCLOAK_CLIENT_SECRET": "<injected by your secret manager>"
      }
    }
  }
}

Run directly

Stdio mode (default)

export KEYCLOAK_URL=https://keycloak.example.com
export KEYCLOAK_REALM=example
export KEYCLOAK_CLIENT_ID=gocloak-mcp
export KEYCLOAK_CLIENT_SECRET='<injected by your secret manager>'
go run ./cmd/gocloak-mcp

Streamable HTTP mode

export MCP_TRANSPORT=http
export MCP_HTTP_ADDR=127.0.0.1:8080
export MCP_HTTP_BEARER_TOKEN='<at least 32 random chars for non-loopback>'
go run ./cmd/gocloak-mcp

Or via Docker:

docker run --rm -p 127.0.0.1:8080:8080 \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_ADDR=0.0.0.0:8080 \
  -e MCP_HTTP_BEARER_TOKEN='<at least 32 random chars>' \
  -e KEYCLOAK_URL=https://keycloak.example.com \
  -e KEYCLOAK_REALM=example \
  -e KEYCLOAK_CLIENT_ID=gocloak-mcp \
  -e KEYCLOAK_CLIENT_SECRET='<injected by your secret manager>' \
  ghcr.io/nerzal/gocloak-mcp:latest

Exposes /mcp (Streamable HTTP MCP endpoint) and /healthz (liveness probe).

Read-Only Tools (32)

All tools declare readOnlyHint: true, idempotentHint: true, and destructiveHint: false, accept an optional realm parameter checked against KEYCLOAK_ALLOWED_REALMS, cap pagination at max <= 100 (default 50), and return safe allowlist DTOs (never exposing credentials, client secrets, IdP config secrets, or raw admin-event payloads).

  • Users: list_users, get_user, count_users, get_user_sessions, get_user_groups, get_user_roles
  • Clients & Scopes: list_clients, get_client, get_client_service_account, list_client_roles, list_client_scopes, get_client_scope
  • Roles: list_realm_roles, get_realm_role, get_users_in_role, get_users_in_client_role
  • Groups: list_groups, count_groups, get_group, get_group_members, get_group_roles
  • Realms & Events: list_realms, get_realm_info, list_events, list_admin_events
  • Auth Flows & Required Actions: list_authentication_flows, get_flow_executions, list_required_actions
  • Identity Providers: list_identity_providers, get_identity_provider
  • Organizations (Keycloak 26+): list_organizations, get_organization_members

Build and verification

make check

Building the container locally

docker build -t gocloak-mcp .
OCI
ghcr.io/nerzal/gocloak-mcp:0.3.0
Install Command
docker pull ghcr.io/nerzal/gocloak-mcp:0.3.0:undefined