io.github.dockndevai/mcp-keycloak
Keycloak admin for AI agents — realms, users, clients, roles; safe-by-default governance.
Open source Open in the app JSON README (API)
About
Keycloak admin for AI agents — realms, users, clients, roles; safe-by-default governance.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- dockndevai
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Stars
- 1
- Open pull requests
- 6
- Last push
- 2026-09-04T05:25:00Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:43
- Updated
- 2026-08-30 07:00:12
- Origin id
io.github.dockndevai/mcp-keycloak
README
# mcp-keycloak
[](https://github.com/dockndevai/mcp-keycloak/actions/workflows/ci.yml)
[](./LICENSE)
[](https://www.npmjs.com/package/@dockndevai/mcp-keycloak)
A [Model Context Protocol](https://modelcontextprotocol.io) server for **Keycloak**. It lets an MCP-capable client (Claude Desktop, Claude Code, etc.) inspect and manage Keycloak realms, users, clients, roles, and groups — with security controlled entirely by flags.
The design goal is **safe by default**: it starts read-only, scopes to an allowlist of realms, protects sensitive realms from mutation, and gates destructive operations behind an explicit opt-in.
## Features
- **Multi-realm** — every tool takes a `realm` argument; scope it with an allowlist.
- **Access modes** — `read-only` → `read-write` → `admin`, layered so a mode never exposes tools above its level.
- **Security flags** — realm allowlist, protected realms, delete gating, dry-run, and JSON audit logging (see below).
- **Two auth strategies** — confidential-client service account (recommended) or admin username/password.
- **Zero heavy dependencies** — a thin fetch-based Admin REST client, plus the MCP SDK and zod.
## Security model
| Concern | Flag | Default | Effect |
| --- | --- | --- | --- |
| What can the server do at all? | `KEYCLOAK_MODE` | `read-only` | `read-only` exposes only read tools; `read-write` adds mutations; `admin` adds destructive tools. Tools above the mode are **never registered**. |
| Which realms are in scope? | `KEYCLOAK_REALM_ALLOWLIST` | *(all)* | Comma-separated. When set, any operation on a realm outside the list is refused. |
| Which realms are read-only forever? | `KEYCLOAK_PROTECTED_REALMS` | `master` | Protected realms can be read but never mutated or deleted, regardless of mode. |
| Can it delete? | `KEYCLOAK_ALLOW_DELETE` | `false` | `delete_*` tools require this **and** admin mode. |
| Preview without touching Keycloak | `KEYCLOAK_DRY_RUN` | `false` | Write/admin tools validate + log intent, then return without calling Keycloak. |
| Audit trail | `KEYCLOAK_AUDIT_LOG` | `true` | Emits a JSON line to stderr per guarded operation (`ALLOW` / `DENY` / `DRY_RUN`). |
These layers are independent — for example `admin` mode with `KEYCLOAK_ALLOW_DELETE=false` can create and update users but cannot delete them.
## Tools
**Read** (`read-only`+): `list_realms`, `get_realm`, `list_users`, `get_user`, `count_users`, `list_clients`, `list_realm_roles`, `list_groups`
**Write** (`read-write`+): `create_user`, `update_user`, `reset_password`, `logout_user`
**Admin** (`admin`): `delete_user`
## Quickstart — add to your agent
Published on npm as [`@dockndevai/mcp-keycloak`](https://www.npmjs.com/package/@dockndevai/mcp-keycloak). No clone or build needed — your MCP client runs it on demand with `npx`. **Start in `read-only` mode**; see [`.env.example`](.env.example) for every variable and [docs/CLIENTS.md](docs/CLIENTS.md) for the full per-client guide.
**Claude Code** (CLI)
```bash
claude mcp add keycloak -e KEYCLOAK_URL="https://keycloak.example.com" -e KEYCLOAK_CLIENT_ID="admin-cli" -e KEYCLOAK_CLIENT_SECRET="your-secret" -e KEYCLOAK_MODE="read-only" -- npx -y @dockndevai/mcp-keycloak
```
**Claude Desktop · Cursor · Windsurf** — same block in `claude_desktop_config.json`, `.cursor/mcp.json`, or `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"keycloak": {
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-keycloak"
],
"env": {
"KEYCLOAK_URL": "https://keycloak.example.com",
"KEYCLOAK_CLIENT_ID": "admin-cli",
"KEYCLOAK_CLIENT_SECRET": "your-secret",
"KEYCLOAK_MODE": "read-only"
}
}
}
}
```
**OpenAI Codex CLI** — in `~/.codex/config.toml`:
```toml
[mcp_servers.keycloak]
command = "npx"
args = ["-y", "@dockndevai/mcp-keycloak"]
env = { KEYCLOAK_URL = "https://keycloak.example.com", KEYCLOAK_CLIENT_ID = "admin-cli", KEYCLOAK_CLIENT_SECRET = "your-secret", KEYCLOAK_MODE = "read-only" }
```
**VS Code (GitHub Copilot, Agent mode)** — in `.vscode/mcp.json`:
```json
{
"servers": {
"keycloak": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-keycloak"
],
"env": {
"KEYCLOAK_URL": "https://keycloak.example.com",
"KEYCLOAK_CLIENT_ID": "admin-cli",
"KEYCLOAK_CLIENT_SECRET": "your-secret",
"KEYCLOAK_MODE": "read-only"
}
}
}
}
```
## Configure
Copy `.env.example` and fill it in, or set the variables directly in your MCP client config. A confidential client with the `realm-management` roles you need is the recommended credential.
## Run from source (development)
Prefer the published package above. To run from a clone:
```bash
npm install
npm run build
node dist/index.js # with the environment variables set
```
## Develop
```bash
npm run dev # watch mode
npm test # unit tests for the security policy
npm run typecheck
```
## Publishing
This server ships a [`server.json`](server.json) for the official MCP registry and an [`mcpName`](package.json) for npm ownership validation. See **[PUBLISHING.md](PUBLISHING.md)** for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.
## License
MIT