mcp-keycloak

mcp-keycloak

Un servidor de Model Context Protocol para Keycloak. Permite que un cliente compatible con MCP (Claude Desktop, Claude Code, etc.) inspeccione y gestione realms, usuarios, clientes, roles y grupos de Keycloak, con la seguridad controlada completamente mediante flags.

El objetivo de diseño es seguro por defecto: comienza en modo solo lectura, se limita a una lista de realms permitidos, protege realms sensibles de mutaciones y condiciona las operaciones destructivas a una aceptación explícita.

Características

• Multi-realm — cada herramienta acepta un argumento realm; delimítalo con una lista de permitidos.
• Modos de acceso — read-only → read-write → admin, en capas de modo que un modo nunca exponga herramientas por encima de su nivel.
• Flags de seguridad — lista de realms permitidos, realms protegidos, control de eliminación, simulación (dry-run) y registro de auditoría JSON (ver más abajo).
• Dos estrategias de autenticación — cuenta de servicio de cliente confidencial (recomendada) o nombre de usuario/contraseña de administrador.
• Cero dependencias pesadas — un cliente REST de administración delgado basado en fetch, además del SDK de MCP y zod.

Modelo de seguridad

Aspecto	Flag	Predeterminado	Efecto
¿Qué puede hacer el servidor en general?	KEYCLOAK_MODE	read-only	read-only expone solo herramientas de lectura; read-write añade mutaciones; admin añade herramientas destructivas. Las herramientas por encima del modo nunca se registran.
¿Qué realms están en alcance?	KEYCLOAK_REALM_ALLOWLIST	(todos)	Separados por comas. Cuando se establece, cualquier operación sobre un realm fuera de la lista es rechazada.
¿Qué realms son de solo lectura para siempre?	KEYCLOAK_PROTECTED_REALMS	master	Los realms protegidos pueden leerse pero nunca mutarse ni eliminarse, independientemente del modo.
¿Puede eliminar?	KEYCLOAK_ALLOW_DELETE	false	Las herramientas delete_* requieren esto y el modo administrador.
Vista previa sin tocar Keycloak	KEYCLOAK_DRY_RUN	false	Las herramientas de escritura/administración validan y registran la intención, luego regresan sin llamar a Keycloak.
Rastro de auditoría	KEYCLOAK_AUDIT_LOG	true	Emite una línea JSON a stderr por operación protegida (ALLOW / DENY / DRY_RUN).

Estas capas son independientes; por ejemplo, el modo admin con KEYCLOAK_ALLOW_DELETE=false puede crear y actualizar usuarios pero no eliminarlos.

Herramientas

Lectura (read-only+): list_realms, get_realm, list_users, get_user, count_users, list_clients, list_realm_roles, list_groups

Escritura (read-write+): create_user, update_user, reset_password, logout_user

Administración (admin): delete_user

Inicio rápido — añádelo a tu agente

Publicado en npm como @dockndevai/mcp-keycloak. No se necesita clonar ni compilar: tu cliente MCP lo ejecuta bajo demanda con npx. Comienza en modo read-only; consulta .env.example para cada variable y docs/CLIENTS.md para la guía completa por cliente.

Claude Code (CLI)

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 — el mismo bloque en claude_desktop_config.json, .cursor/mcp.json o ~/.codeium/windsurf/mcp_config.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 — en ~/.codex/config.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, modo Agente) — en .vscode/mcp.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"
      }
    }
  }
}

Configuración

Copia .env.example y complétalo, o establece las variables directamente en la configuración de tu cliente MCP. Un cliente confidencial con los roles realm-management que necesites es la credencial recomendada.

Ejecutar desde el código fuente (desarrollo)

Prefiere el paquete publicado anteriormente. Para ejecutar desde un clon:

npm install
npm run build
node dist/index.js   # with the environment variables set

Desarrollo

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

Publicación

Este servidor incluye un server.json para el registro oficial de MCP y un mcpName para la validación de propiedad en npm. Consulta PUBLISHING.md para publicar en npm y listarlo en el registro de MCP, Smithery, Glama, Cursor y PulseMCP.

Licencia

MIT