gocloak-mcp
OfficialProvides read-only tools for querying Keycloak resources, including users, clients, client scopes, roles, groups, realms, events, authentication flows, required actions, identity providers, and Keycloak 26+ organizations, with multi-realm allowlisting and safe DTOs.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| Yes | — | HTTPS Keycloak base URL (a |
| Yes | — | Default target realm and token-issuing realm |
| No |
| Comma-separated allowlist of realms tools may query ( |
| Yes | — | Service-account client ID |
| Yes | — | Service-account client secret |
| No |
| Per-request timeout; valid range is |
| No |
| Transport mode: |
| No |
| Listen address when |
| Conditional | — | Optional on loopback; required (min 32 chars) when |
| No | Loopback only | Comma-separated additional |
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 toolsquery-clients,view-clients— client, client-role, and client-scope toolsquery-groups— group toolsview-realm— realm, role, auth-flow, required-action, and IdP toolsview-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-mcpPrebuilt 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:latestThe 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@latestMCP 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-mcpStreamable 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-mcpOr 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:latestExposes /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_rolesClients & Scopes:
list_clients,get_client,get_client_service_account,list_client_roles,list_client_scopes,get_client_scopeRoles:
list_realm_roles,get_realm_role,get_users_in_role,get_users_in_client_roleGroups:
list_groups,count_groups,get_group,get_group_members,get_group_rolesRealms & Events:
list_realms,get_realm_info,list_events,list_admin_eventsAuth Flows & Required Actions:
list_authentication_flows,get_flow_executions,list_required_actionsIdentity Providers:
list_identity_providers,get_identity_providerOrganizations (Keycloak 26+):
list_organizations,get_organization_members
Build and verification
make checkBuilding 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Managed Keycloak from any MCP client: clusters, realms, apps, SSO, users, domains, audit events.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Related MCP Servers
- AlicenseAqualityBmaintenanceRead-only MCP server for safe Kubernetes inspection, diagnosis, and debugging. Supports Kubernetes core, Helm, Argo Workflows, and Argo CD.2133 npm5MIT
- AlicenseCqualityDmaintenanceA 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.100MIT
- AlicenseAqualityBmaintenanceEnables 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.859 npm1MIT
- AlicenseAqualityBmaintenanceEnables 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.4Apache 2.0