mcp-keycloak

Un servidor de Model Context Protocol para Keycloak. Permite a un cliente compatible con MCP (Claude Desktop, Claude Code, etc.) inspeccionar y administrar los realms, usuarios, clientes, roles y grupos de Keycloak, con la seguridad controlada por completo mediante flags.

El objetivo de diseño es ser seguro por defecto: inicia en modo de solo lectura, limita el alcance a una lista de permitidos de realms, protege los realms protegidos frente a modificaciones y restringe las operaciones destructivas a una habilitación explícita.

Características

• Multi-realm — toda herramienta recibe un argumento realm; delimítalo con una lista de permitidos.

• Modos de acceso — read-only → read-write → admin, ordenados en capas para que un modo nunca exponga herramientas por encima de su nivel.

• Flags de seguridad — lista de permitidos de realms, realms protegidos, número de intentos de borrado, 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 ligero y basado en fetch, más el MCP SDK y zod.

Related MCP server: mcp-keycloak-admin

Modelo de seguridad

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

Tools

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

Uso con tu cliente MCP

Funciona con Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code (Copilot) y cualquier otro cliente de MCP; consulta docs/CLIENTS.md para la configuración de cada cliente.

Instalación

npm install
npm run build

Configuración

Copia .env.example y complétalo, o establece las variables directamente en la configuración de tu cliente de MCP. Una credencial con los roles de realm-management que necesites y un cliente confidencial es lo más recomendado.

Ejecutar con Claude Desktop / Claude Code

Añade la configuración de tu cliente de MCP (claude_desktop_config.json o a través de claude mcp add):

{
  "mcpServers": {
    "keycloak": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-keycloak/dist/index.js"],
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_CLIENT_ID": "admin-cli",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "KEYCLOAK_MODE": "read-only",
        "KEYCLOAK_REALM_ALLOWLIST": "app,customers"
      }
    }
  }
}

Sube KEYCLOAK_MODE a read-write (y, para eliminar, admin + KEYCLOAK_ALLOW_DELETE=true) solo cuando quieras permitir que el modelo realice cambios.

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 validar la titularidad del paquete en npm. Consulta PUBLISHING.md para publicar en npm y aparecer en el registro de MCP, Smithery, Glama, Cursor y PulseMCP.

Licencia

MIT