mcp-keycloak-admin

A Model Context Protocol (MCP) server to administer a Keycloak instance through its Admin REST API. Safe by default, configurable, and built with a clean, test-driven architecture.

Compatible with Keycloak 26.x (validated against 26.0.5).

Install

No install needed — run it straight from npm with npx:

npx -y mcp-keycloak-admin

The server speaks MCP over stdio, so you normally wire it into an MCP client rather than running it by hand — see Usage with an MCP client. New to it? The Quickstart spins up a local Keycloak and a client config in a couple of minutes.

Why

Administering Keycloak from an MCP client (an assistant, an IDE, a custom agent) means exposing day-to-day operations — searching users, managing roles, reading events — as MCP tools, without handing over a raw admin console. This server does that with strong guardrails so destructive actions never happen silently.

Features

• Two authentication modes, selectable by configuration:
  • service_account — a confidential client with a service account (recommended; no admin password stored).
  • password — the admin-cli client with an admin username/password.
• Safe by default:
  • READ_ONLY mode hides every write/destructive tool.
  • ALLOWED_REALMS restricts which realms the server may operate on.
  • Destructive operations require explicit confirmation (native MCP elicitation, with a confirm: true parameter fallback for clients that do not support elicitation).
• Clean Architecture: a framework-free domain, application use cases, and infrastructure adapters. No business concept travels as a raw string or number — every one is a validated value object.

Requirements

• Node.js >= 20
• A reachable Keycloak 26.x server

Usage with an MCP client

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "keycloak-admin": {
      "command": "npx",
      "args": ["-y", "mcp-keycloak-admin"],
      "env": {
        "KEYCLOAK_BASE_URL": "http://localhost:8080",
        "KEYCLOAK_REALM": "demo-realm",
        "AUTH_MODE": "service_account",
        "KC_CLIENT_ID": "mcp-admin",
        "KC_CLIENT_SECRET": "your-secret"
      }
    }
  }
}

See docs/setup-keycloak.md to create the mcp-admin client and grant it the least-privilege roles it needs.

Multiple Keycloak instances

Each server entry targets one Keycloak (one base URL + realm + auth). To manage several environments, add one entry per instance — each fully isolated, with its own credentials and guardrails:

{
  "mcpServers": {
    "kc-preprod": {
      "command": "npx",
      "args": ["-y", "mcp-keycloak-admin"],
      "env": {
        "KEYCLOAK_BASE_URL": "https://preprod.example.com",
        "KEYCLOAK_REALM": "preprod-realm",
        "AUTH_MODE": "service_account",
        "KC_CLIENT_ID": "mcp-admin",
        "KC_CLIENT_SECRET": "…",
        "ALLOWED_REALMS": "preprod-realm"
      }
    },
    "kc-prod": {
      "command": "npx",
      "args": ["-y", "mcp-keycloak-admin"],
      "env": {
        "KEYCLOAK_BASE_URL": "https://auth.example.com",
        "KEYCLOAK_REALM": "prod-realm",
        "AUTH_MODE": "service_account",
        "KC_CLIENT_ID": "mcp-admin",
        "KC_CLIENT_SECRET": "…",
        "READ_ONLY": "true",
        "ALLOWED_REALMS": "prod-realm"
      }
    }
  }
}

The client namespaces the tools per server (e.g. kc-prod:keycloak_user_delete), so there's no risk of running an operation against the wrong environment. This is the recommended pattern: you can, for example, keep production READ_ONLY while preprod stays writable.

Configuration

A full example lives in .env.example.

Tools

Levels: [R] read-only · [W] write · [D] destructive (requires confirmation). Every tool carries the matching MCP annotations (readOnlyHint / destructiveHint / idempotentHint).

Currently implemented:

Note: this table tracks the main branch, which can run ahead of the latest npm release shown by the version badge above. To confirm what's available in your install, check npm view mcp-keycloak-admin version and pin mcp-keycloak-admin@latest.

See docs/users.md, docs/roles.md, docs/clients.md, docs/groups.md and docs/events-realm.md for parameters and examples, and docs/security.md for the safety model.

Roadmap

The architecture is designed to keep growing as thin use cases + tools. Remaining candidates: authorization policy/permission CRUD and evaluation, authentication flow mutation (copy/add executions), and advanced federation and identity-provider configuration. See docs/development.md for how to add one.

Development

npm install
npm test              # unit tests
npm run test:integration  # spins up a real Keycloak 26 via Testcontainers (needs Docker)
npm run check         # typecheck + lint + format check + unit tests
npm run build         # bundle to dist/

Releases are automated — see docs/releasing.md.

Contributing

Contributions are welcome — please read CONTRIBUTING.md.

License

MIT