Skip to main content
Glama
gocloak-mcp

gocloak-mcp

Official
by Nerzal

gocloak-mcp

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.

Requirements

  • Go 1.26.11 or newer

  • A Keycloak confidential client with service accounts enabled

  • A client secret supplied through the environment

Related MCP server: LimaCharlie MCP

Configuration

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

Environment variable

Required

Default

Description

KEYCLOAK_URL

Yes

—

HTTPS Keycloak base URL (a /auth prefix is allowed); loopback HTTP is allowed for local development

KEYCLOAK_REALM

Yes

—

Default target realm and token-issuing realm

KEYCLOAK_ALLOWED_REALMS

No

KEYCLOAK_REALM

Comma-separated allowlist of realms tools may query (KEYCLOAK_REALM is always included)

KEYCLOAK_CLIENT_ID

Yes

—

Service-account client ID

KEYCLOAK_CLIENT_SECRET

Yes

—

Service-account client secret

KEYCLOAK_REQUEST_TIMEOUT

No

15s

Per-request timeout; valid range is > 0 and <= 2m

MCP_TRANSPORT

No

stdio

Transport mode: stdio or http (Streamable HTTP)

MCP_HTTP_ADDR

No

127.0.0.1:8080

Listen address when MCP_TRANSPORT=http

MCP_HTTP_BEARER_TOKEN

Conditional

—

Optional on loopback; required (min 32 chars) when MCP_HTTP_ADDR binds to a non-loopback address

MCP_HTTP_ALLOWED_ORIGINS

No

Loopback only

Comma-separated additional Origin allowlist for browser clients on Streamable HTTP (DNS rebinding protection)

See Security & Benchmarks for the full OWASP MCP Top 10 control matrix and Go vs. Java/Python benchmark comparison.

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 .

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A local MCP server for the LimaCharlie security platform that provides investigation, administration, and content-review workflows via a broad read-only tool surface with explicit organization scoping and audit logging.
      100
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP-capable clients to inspect and manage Keycloak realms, users, clients, roles, and groups with layered security modes, realm allowlisting, protected realms, delete gating, dry-run, and audit logging.
      8
      59 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP-aware agents to read and explore Oracle Cloud Infrastructure — listing, fetching, and searching across 39 resource types spanning Identity, Compute, Block Volume, Networking, Object Storage, and OKE. Runs locally over stdio using credentials from ~/.oci/config, with fail-closed safety gates and audit logging governing future write operations.
      4
      Apache 2.0