Skip to content
Back to search

gocloak-mcp

Keycloak MCP based on gocloak

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Nerzal/gocloak-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Nerzal/gocloak-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nerzal--gocloak-mcp/badge.svg)](/listings/nerzal--gocloak-mcp)

HTML

<a href="/listings/nerzal--gocloak-mcp"><img src="/api/listings/nerzal--gocloak-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://github.com/Nerzal/gocloak-mcp/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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 202 lines
  1. # gocloak-mcp
  2. A security-first, read-only Keycloak MCP server built in Go with the official
  3. MCP Go SDK and GoCloak v15. Supports **Stdio** (default) and **Streamable HTTP**
  4. transports, multi-realm allowlisting, and full read-only parity across Users,
  5. Clients, Client Scopes, Roles, Groups, Realms, Events, Authentication Flows,
  6. Required Actions, Identity Providers, and Keycloak 26+ Organizations.
  7. In Stdio mode, standard output is strictly reserved for JSON-RPC frames and all
  8. structured JSON logs are written to standard error with automatic redaction.
  9. ## Requirements
  10. - Go 1.26.11 or newer
  11. - A Keycloak confidential client with service accounts enabled
  12. - A client secret supplied through the environment
  13. ## Configuration
  14. The server validates configuration before it starts and exits without printing
  15. secrets when validation fails.
  16. | Environment variable | Required | Default | Description |
  17. | --- | --- | --- | --- |
  18. | `KEYCLOAK_URL` | Yes | — | HTTPS Keycloak base URL (a `/auth` prefix is allowed); loopback HTTP is allowed for local development |
  19. | `KEYCLOAK_REALM` | Yes | — | Default target realm and token-issuing realm |
  20. | `KEYCLOAK_ALLOWED_REALMS` | No | `KEYCLOAK_REALM` | Comma-separated allowlist of realms tools may query (`KEYCLOAK_REALM` is always included) |
  21. | `KEYCLOAK_CLIENT_ID` | Yes | — | Service-account client ID |
  22. | `KEYCLOAK_CLIENT_SECRET` | Yes | — | Service-account client secret |
  23. | `KEYCLOAK_REQUEST_TIMEOUT` | No | `15s` | Per-request timeout; valid range is `> 0` and `<= 2m` |
  24. | `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` (Streamable HTTP) |
  25. | `MCP_HTTP_ADDR` | No | `127.0.0.1:8080` | Listen address when `MCP_TRANSPORT=http` |
  26. | `MCP_HTTP_BEARER_TOKEN` | Conditional | — | Optional on loopback; **required (min 32 chars)** when `MCP_HTTP_ADDR` binds to a non-loopback address |
  27. | `MCP_HTTP_ALLOWED_ORIGINS` | No | Loopback only | Comma-separated additional `Origin` allowlist for browser clients on Streamable HTTP (DNS rebinding protection) |
  28. See [Security & Benchmarks](docs/SECURITY_AND_BENCHMARKS.md) for the full OWASP MCP Top 10 control matrix and reproducible head-to-head benchmarks against other Keycloak MCP servers (`ubuntu-latest`, 4 vCPU, identical local mock Keycloak):
  29. | Server | Transport | Binary / Image | Cold Start | RSS (Load) | Throughput |
  30. | --- | --- | ---: | ---: | ---: | ---: |
  31. | **`gocloak-mcp` (Go)** | **Stdio / HTTP** | **10.0 MB / 21.4 MB** | **12.2 ms / 21.8 ms** | **16.3 MB / 19.5 MB** | **955 / 1,195 req/s** |
  32. | `HaithamOumerzoug/keycloak-mcp` (TS/Node) | Stdio | Node runtime | 68.5 ms | 88.7 MB | 728 req/s |
  33. | `idoyudha/mcp-keycloak` (Python/FastMCP) | Stdio | Python venv | 359.3 ms | 64.2 MB | 272 req/s |
  34. | `sshaaf/keycloak-mcp-server` (Quarkus Native) | HTTP | 74.1 MB | 43.2 ms | 158.8 MB | 214 req/s |
  35. | `sshaaf/keycloak-mcp-server` (Quarkus JVM) | HTTP | 23.4 MB JAR / 626 MB | 1,249.8 ms | 319.9 MB | 252 req/s |
  36. Use your deployment platform's secret manager to provide secrets. Do not put
  37. credentials in command-line arguments, configuration files, or logs.
  38. ## Minimal Keycloak permissions
  39. Create a dedicated confidential client with service accounts enabled and assign
  40. only the read-only `realm-management` roles required for the tools you use:
  41. - `query-users`, `view-users` — user, session, and group-membership tools
  42. - `query-clients`, `view-clients` — client, client-role, and client-scope tools
  43. - `query-groups` — group tools
  44. - `view-realm` — realm, role, auth-flow, required-action, and IdP tools
  45. - `view-events` — login and admin event tools
  46. Do not use the `master` realm or grant `realm-admin` unless explicitly required.
  47. ## Installation
  48. ### Homebrew (macOS & Linux)
  49. ```sh
  50. brew install --cask nerzal/tap/gocloak-mcp
  51. ```
  52. ### Prebuilt binaries (GitHub Releases)
  53. Download the archive for your platform (`darwin`, `linux`, `windows` for `amd64` and `arm64`) from the [GitHub Releases](https://github.com/Nerzal/gocloak-mcp/releases) page, verify the SHA-256 checksum against `checksums.txt`, and place `gocloak-mcp` on your `PATH`.
  54. ### Docker / GHCR (multi-arch: `linux/amd64`, `linux/arm64`)
  55. ```sh
  56. docker pull ghcr.io/nerzal/gocloak-mcp:latest
  57. ```
  58. The image contains a static binary on `gcr.io/distroless/static-debian12:nonroot`.
  59. ### Go install (from source)
  60. ```sh
  61. go install github.com/Nerzal/gocloak-mcp/cmd/gocloak-mcp@latest
  62. ```
  63. ## MCP client configuration
  64. ### Native binary (Stdio)
  65. Works with Claude Desktop, Cursor, VS Code, Claude Code, and other Stdio MCP clients:
  66. ```json
  67. {
  68. "mcpServers": {
  69. "keycloak": {
  70. "command": "gocloak-mcp",
  71. "env": {
  72. "KEYCLOAK_URL": "https://keycloak.example.com",
  73. "KEYCLOAK_REALM": "example",
  74. "KEYCLOAK_CLIENT_ID": "gocloak-mcp",
  75. "KEYCLOAK_CLIENT_SECRET": "<injected by your secret manager>"
  76. }
  77. }
  78. }
  79. }
  80. ```
  81. ### Docker container (Stdio)
  82. Run isolated without installing a local binary:
  83. ```json
  84. {
  85. "mcpServers": {
  86. "keycloak": {
  87. "command": "docker",
  88. "args": [
  89. "run", "-i", "--rm",
  90. "-e", "KEYCLOAK_URL",
  91. "-e", "KEYCLOAK_REALM",
  92. "-e", "KEYCLOAK_CLIENT_ID",
  93. "-e", "KEYCLOAK_CLIENT_SECRET",
  94. "ghcr.io/nerzal/gocloak-mcp:latest"
  95. ],
  96. "env": {
  97. "KEYCLOAK_URL": "https://keycloak.example.com",
  98. "KEYCLOAK_REALM": "example",
  99. "KEYCLOAK_CLIENT_ID": "gocloak-mcp",
  100. "KEYCLOAK_CLIENT_SECRET": "<injected by your secret manager>"
  101. }
  102. }
  103. }
  104. }
  105. ```
  106. ## Run directly
  107. ### Stdio mode (default)
  108. ```sh
  109. export KEYCLOAK_URL=https://keycloak.example.com
  110. export KEYCLOAK_REALM=example
  111. export KEYCLOAK_CLIENT_ID=gocloak-mcp
  112. export KEYCLOAK_CLIENT_SECRET='<injected by your secret manager>'
  113. go run ./cmd/gocloak-mcp
  114. ```
  115. ### Streamable HTTP mode
  116. ```sh
  117. export MCP_TRANSPORT=http
  118. export MCP_HTTP_ADDR=127.0.0.1:8080
  119. export MCP_HTTP_BEARER_TOKEN='<at least 32 random chars for non-loopback>'
  120. go run ./cmd/gocloak-mcp
  121. ```
  122. Or via Docker:
  123. ```sh
  124. docker run --rm -p 127.0.0.1:8080:8080 \
  125. -e MCP_TRANSPORT=http \
  126. -e MCP_HTTP_ADDR=0.0.0.0:8080 \
  127. -e MCP_HTTP_BEARER_TOKEN='<at least 32 random chars>' \
  128. -e KEYCLOAK_URL=https://keycloak.example.com \
  129. -e KEYCLOAK_REALM=example \
  130. -e KEYCLOAK_CLIENT_ID=gocloak-mcp \
  131. -e KEYCLOAK_CLIENT_SECRET='<injected by your secret manager>' \
  132. ghcr.io/nerzal/gocloak-mcp:latest
  133. ```
  134. Exposes `/mcp` (Streamable HTTP MCP endpoint) and `/healthz` (liveness probe).
  135. ## Read-Only Tools (32)
  136. All tools declare `readOnlyHint: true`, `idempotentHint: true`, and
  137. `destructiveHint: false`, accept an optional `realm` parameter checked against
  138. `KEYCLOAK_ALLOWED_REALMS`, cap pagination at `max <= 100` (default `50`), and
  139. return safe allowlist DTOs (never exposing credentials, client secrets, IdP
  140. config secrets, or raw admin-event payloads).
  141. - **Users:** `list_users`, `get_user`, `count_users`, `get_user_sessions`, `get_user_groups`, `get_user_roles`
  142. - **Clients & Scopes:** `list_clients`, `get_client`, `get_client_service_account`, `list_client_roles`, `list_client_scopes`, `get_client_scope`
  143. - **Roles:** `list_realm_roles`, `get_realm_role`, `get_users_in_role`, `get_users_in_client_role`
  144. - **Groups:** `list_groups`, `count_groups`, `get_group`, `get_group_members`, `get_group_roles`
  145. - **Realms & Events:** `list_realms`, `get_realm_info`, `list_events`, `list_admin_events`
  146. - **Auth Flows & Required Actions:** `list_authentication_flows`, `get_flow_executions`, `list_required_actions`
  147. - **Identity Providers:** `list_identity_providers`, `get_identity_provider`
  148. - **Organizations (Keycloak 26+):** `list_organizations`, `get_organization_members`
  149. ## Build and verification
  150. ```sh
  151. make check
  152. ```
  153. ## Building the container locally
  154. ```sh
  155. docker build -t gocloak-mcp .
  156. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.