Keycloak MCP Server

Servidor de Protocolo de Contexto Modelo de Keycloak

Un servidor integral del Protocolo de Contexto Modelo (MCP) para la administración de Keycloak, que proporciona más de 80 herramientas para gestionar usuarios, dominios, clientes, roles, grupos, sesiones, eventos, organizaciones, mapeadores de protocolo, atributos de usuario, ámbitos de cliente y proveedores de identidad directamente desde asistentes de IA como Claude Desktop o Cursor AI.

🚀 Características

👤 Gestión de Usuarios

• ✅ Crear, actualizar y eliminar usuarios
• ✅ Listar, buscar y obtener detalles de usuarios
• ✅ Restablecer contraseñas de usuarios
• ✅ Cerrar sesiones de usuarios
• ✅ Gestionar roles y grupos de usuarios
• ✅ NUEVO: Gestión de atributos de usuario (crítico para datos de organización)

🏛️ Gestión de Dominios

• ✅ Listar, crear, actualizar y eliminar dominios
• ✅ Obtener configuraciones y ajustes detallados de dominios
• ✅ Gestionar políticas de seguridad a nivel de dominio

🔧 Gestión de Clientes

• ✅ Registrar, actualizar y eliminar clientes/aplicaciones
• ✅ Listar todos los clientes en dominios
• ✅ Configurar ajustes de cliente y URI de redirección
• ✅ NUEVO: Gestión de mapeadores de protocolo (crítico para reclamaciones JWT)

🎭 Gestión de Roles

• ✅ Crear, actualizar y eliminar roles (a nivel de dominio y cliente)
• ✅ Asignar y eliminar roles de usuarios y grupos
• ✅ Listar todos los roles y asignaciones de roles de usuario
• ✅ NUEVO: Roles compuestos y jerarquías de roles
• ✅ NUEVO: Operaciones avanzadas de roles por ID
• ✅ NUEVO: Encontrar usuarios con roles específicos

👥 Gestión de Grupos

• ✅ Crear, actualizar y eliminar grupos de usuarios
• ✅ Agregar y eliminar usuarios de grupos
• ✅ Gestionar estructuras jerárquicas de grupos
• ✅ NUEVO: Gestión de atributos de grupo
• ✅ NUEVO: Gestión de subgrupos y grupos secundarios
• ✅ NUEVO: Listado y gestión de miembros de grupo

🏢 Gestión de Organizaciones ⭐ NUEVO

• ✅ Crear, actualizar y eliminar organizaciones
• ✅ Agregar y eliminar miembros de organización
• ✅ Listar organizaciones y miembros
• ✅ Gestión de atributos de organización

🔗 Gestión de Proveedores de Identidad ⭐ NUEVO

• ✅ Crear, actualizar y eliminar proveedores de identidad (SSO)
• ✅ Gestión de mapeadores de proveedores de identidad
• ✅ Configuración de proveedores SAML y OIDC
• ✅ Mapeo de atributos de usuario externos

🎯 Gestión de Ámbitos de Cliente ⭐ NUEVO

• ✅ Crear, actualizar y eliminar ámbitos de cliente
• ✅ Mapeadores de protocolo para ámbitos de cliente
• ✅ Gestión de ámbitos de token

📊 Gestión de Sesiones y Eventos

• ✅ Listar sesiones de usuario activas
• ✅ Monitorear eventos de autenticación y administración
• ✅ Limpiar registros de eventos y gestionar ciclos de vida de sesiones

🛡️ Características Avanzadas

• ✅ Autenticación a prueba de fallos con instancias de cliente nuevas
• ✅ Manejo integral de errores con registro detallado
• ✅ Soporte multiplataforma (Windows, macOS, Linux)
• ✅ Listo para producción con TypeScript y arquitectura robusta
• ✅ Reclamaciones JWT de Organización - Resolver la visibilidad de la organización en tokens
• ✅ Más de 80 herramientas - Cobertura completa de administración de Keycloak

📋 Requisitos Previos

• Node.js 18 o superior
• Instancia de Keycloak en ejecución (local o remota)
• Credenciales de administrador de Keycloak con permisos apropiados
• Asistente de IA que admita MCP (Claude Desktop, Cursor AI, etc.)

📦 Instalación

Instalación Global (Recomendada)

npm install -g keycloak-mcp-server

Usando NPX (Sin Instalación Requerida)

npx keycloak-mcp-server

Instalación Local del Proyecto

npm install keycloak-mcp-server

Desarrollo Local

git clone https://github.com/M0-AR/keycloak-mcp-server.git
cd keycloak-mcp-server
npm install
npm run build

⚙️ Configuración

Para Cursor AI

Agregue a su archivo de configuración MCP de Cursor (~/.cursor/mcp.json):

Opción 1: Usando NPX (Recomendado)

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["keycloak-mcp-server"],
      "env": {
        "KEYCLOAK_URL": "https://your-keycloak-instance.com",
        "KEYCLOAK_ADMIN": "your-admin-username",
        "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}

Opción 2: Si está Instalado Globalmente

{
  "mcpServers": {
    "keycloak": {
      "command": "keycloak-mcp-server",
      "env": {
        "KEYCLOAK_URL": "https://your-keycloak-instance.com", 
        "KEYCLOAK_ADMIN": "your-admin-username",
        "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}

Para Claude Desktop

Agregue a su configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "keycloak": {
      "command": "npx",
      "args": ["keycloak-mcp-server"],
      "env": {
        "KEYCLOAK_URL": "https://your-keycloak-instance.com",
        "KEYCLOAK_ADMIN": "your-admin-username",
        "KEYCLOAK_ADMIN_PASSWORD": "your-admin-password"
      }
    }
  }
}

🌍 Variables de Entorno

Variable	Descripción	Predeterminado	Requerido
KEYCLOAK_URL	La URL base de su instancia de Keycloak	http://localhost:8080	✅
KEYCLOAK_ADMIN	Nombre de usuario administrador	admin	✅
KEYCLOAK_ADMIN_PASSWORD	Contraseña de administrador	admin	✅

🛠️ Herramientas Disponibles (Más de 80 Herramientas)

👤 Herramientas de Gestión de Usuarios

create-user

Crea un nuevo usuario en un dominio especificado.

Create a user in "master" realm: username "john.doe", email "john@example.com", first name "John", last name "Doe"

update-user

Actualiza información de usuario (correo electrónico, nombres, estado de habilitación).

Update user "user-id-123" in "master" realm to change email to "newemail@example.com"

delete-user

Elimina un usuario de un dominio.

Delete user with ID "user-id-123" from "master" realm

list-users

Lista todos los usuarios en un dominio.

List all users in the "master" realm

search-users

Busca usuarios con filtros (nombre de usuario, correo electrónico, nombre, apellido).

Search for users with email containing "wateen.io" in "master" realm, limit 10 results

get-user

Obtiene información detallada sobre un usuario específico.

Get details for user ID "user-id-123" in "master" realm

reset-user-password

Restablece la contraseña de un usuario.

Reset password for user "user-id-123" in "master" realm to "newPassword123", make it temporary

logout-user

Cierra todas las sesiones de un usuario específico.

Logout all sessions for user "user-id-123" in "master" realm

set-user-attributes ⭐ NUEVO

Establece atributos de usuario (crítico para el almacenamiento de datos de organización).

Set organization attribute for user "user-id-123" in "master" realm: {"organization": ["wateen-corp"]}

get-user-attributes ⭐ NUEVO

Obtiene atributos de usuario, incluidos atributos no gestionados.

Get all attributes for user "user-id-123" in "master" realm

🏛️ Herramientas de Gestión de Dominios

list-realms

Lista todos los dominios disponibles.

Show me all available realms in Keycloak

create-realm

Crea un nuevo dominio con ajustes configurables.

Create a new realm called "company" with display name "Company Realm", enabled

update-realm

Actualiza ajustes y configuraciones de dominio.

Update realm "company" to change display name to "Updated Company"

delete-realm

Elimina un dominio existente.

Delete the realm "test-realm"

get-realm-settings

Recupera ajustes detallados de un dominio.

Get detailed settings for the "master" realm

🔧 Herramientas de Gestión de Clientes

create-client

Registra un nuevo cliente/aplicación en un dominio.

Create client "my-app" in "master" realm with redirect URIs ["http://localhost:3000/*"]

update-client

Actualiza ajustes de cliente (URI de redirección, mapeadores de protocolo, etc.).

Update client "my-app" in "master" realm to add new redirect URI "https://app.example.com/*"

delete-client

Elimina un cliente de un dominio.

Delete client "old-app" from "master" realm

list-clients

Lista todos los clientes en un dominio.

List all clients in the "master" realm

create-protocol-mapper ⭐ NUEVO

Crea mapeadores de protocolo para clientes (crítico para reclamaciones JWT de organización).

Create organization group mapper for client "my-app" in "master" realm to include "organization" claim in JWT

update-protocol-mapper ⭐ NUEVO

Actualiza mapeadores de protocolo existentes.

Update protocol mapper "mapper-id-123" for client "my-app" in "master" realm

delete-protocol-mapper ⭐ NUEVO

Elimina mapeadores de protocolo de clientes.

Delete protocol mapper "mapper-id-123" from client "my-app" in "master" realm

list-protocol-mappers ⭐ NUEVO

Lista todos los mapeadores de protocolo para un cliente.

List all protocol mappers for client "my-app" in "master" realm

🎯 Herramientas de Gestión de Ámbitos de Cliente ⭐ NUEVO

create-client-scope

Crea un nuevo ámbito de cliente para gestionar ámbitos de token.

Create client scope "organization-scope" in "master" realm for organization claims

update-client-scope

Actualiza un ámbito de cliente existente.

Update client scope "scope-id-123" in "master" realm to change description

delete-client-scope

Elimina un ámbito de cliente.

Delete client scope "scope-id-123" from "master" realm

list-client-scopes

Lista todos los ámbitos de cliente en un dominio.

List all client scopes in the "master" realm

get-client-scope

Obtiene detalles de un ámbito de cliente específico.

Get details for client scope "scope-id-123" in "master" realm

create-client-scope-protocol-mapper ⭐ NUEVO

Crea mapeadores de protocolo para ámbitos de cliente.

Create organization mapper for client scope "organization-scope" in "master" realm

update-client-scope-protocol-mapper ⭐ NUEVO

Actualiza mapeadores de protocolo en ámbitos de cliente.

Update protocol mapper "mapper-id-123" in client scope "scope-id-456" in "master" realm

delete-client-scope-protocol-mapper ⭐ NUEVO

Elimina mapeadores de protocolo de ámbitos de cliente.

Delete protocol mapper "mapper-id-123" from client scope "scope-id-456" in "master" realm

list-client-scope-protocol-mappers ⭐ NUEVO

Lista mapeadores de protocolo para un ámbito de cliente.

List all protocol mappers for client scope "scope-id-123" in "master" realm

🏢 Herramientas de Gestión de Organizaciones ⭐ NUEVO

create-organization

Crea una nueva organización.

Create organization "wateen-corp" with description "Wateen Corporation" in "master" realm

update-organization

Actualiza una organización existente.

Update organization "org-id-123" in "master" realm to change name to "Updated Corp"

delete-organization

Elimina una organización.

Delete organization "org-id-123" from "master" realm

list-organizations

Lista todas las organizaciones en un dominio.

List all organizations in "master" realm with search "wateen", limit 10

get-organization

Obtiene detalles de una organización específica.

Get details for organization "org-id-123" in "master" realm

add-organization-member

Agrega un usuario a una organización.

Add user "user-id-123" to organization "org-id-456" in "master" realm

remove-organization-member

Elimina un usuario de una organización.

Remove user "user-id-123" from organization "org-id-456" in "master" realm

list-organization-members

Lista todos los miembros de una organización.

List all members of organization "org-id-123" in "master" realm, limit 20

🎭 Herramientas de Gestión de Roles

create-role

Crea roles a nivel de dominio o cliente.

Create a realm role "manager" with description "Manager role" in "master" realm

update-role

Modifica atributos de roles.

Update role "manager" in "master" realm to change description to "Updated manager role"

delete-role

Elimina roles.

Delete role "old-role" from "master" realm

list-roles

Lista todos los roles en un dominio.

List all roles in the "master" realm

assign-role-to-user

Asigna un rol a un usuario.

Assign role "manager" to user "user-id-123" in "master" realm

remove-role-from-user

Elimina un rol de un usuario.

Remove role "manager" from user "user-id-123" in "master" realm

get-user-roles

Obtiene todos los roles asignados a un usuario.

Get all roles for user "user-id-123" in "master" realm

create-composite-role ⭐ NUEVO

Crea roles compuestos (jerarquías de roles).

Create composite role from "parent-role-id" with child roles ["child-role-1", "child-role-2"] in "master" realm

get-composite-roles ⭐ NUEVO

Obtiene roles compuestos para un rol.

Get composite roles for role "role-id-123" in "master" realm, limit 10

delete-composite-roles ⭐ NUEVO

Elimina roles compuestos de un rol.

Remove composite roles ["child-role-1", "child-role-2"] from role "parent-role-id" in "master" realm

get-role-by-id ⭐ NUEVO

Obtiene detalles de rol por ID.

Get role details for role ID "role-id-123" in "master" realm

update-role-by-id ⭐ NUEVO

Actualiza rol por ID.

Update role "role-id-123" in "master" realm to change name to "new-role-name"

delete-role-by-id ⭐ NUEVO

Elimina rol por ID.

Delete role with ID "role-id-123" from "master" realm

find-users-with-role ⭐ NUEVO

Encuentra usuarios con un rol específico.

Find all users with role "manager" in "master" realm, limit 20

assign-role-to-group ⭐ NUEVO

Asigna un rol a un grupo.

Assign role "developer" to group "group-id-123" in "master" realm

remove-role-from-group ⭐ NUEVO

Elimina un rol de un grupo.

Remove role "developer" from group "group-id-123" in "master" realm

get-group-roles ⭐ NUEVO

Obtiene roles asignados a un grupo.

Get all roles for group "group-id-123" in "master" realm

list-available-group-roles ⭐ NUEVO

Lista roles disponibles para un grupo.

List available roles for group "group-id-123" in "master" realm

list-composite-group-roles ⭐ NUEVO

Lista roles compuestos para un grupo.

List composite roles for group "group-id-123" in "master" realm

👥 Herramientas de Gestión de Grupos

create-group

Crea grupos de usuarios.

Create a group called "developers" in "master" realm

update-group

Actualiza atributos de grupo.

Update group "group-id-123" in "master" realm to change name to "senior-developers"

delete-group

Elimina grupos.

Delete group "group-id-123" from "master" realm

list-groups

Lista todos los grupos en un dominio.

List all groups in the "master" realm

manage-user-groups

Agrega o elimina usuarios de grupos.

Add user "user-id-123" to group "group-id-456" in "master" realm

set-group-attributes ⭐ NUEVO

Establece atributos de grupo (metadatos de organización).

Set organization attributes for group "group-id-123" in "master" realm: {"department": ["engineering"]}

get-group-attributes ⭐ NUEVO

Obtiene atributos de grupo.

Get all attributes for group "group-id-123" in "master" realm

create-child-group ⭐ NUEVO

Crea un grupo secundario (subgrupo).

Create child group "junior-devs" under parent group "group-id-123" in "master" realm

list-sub-groups ⭐ NUEVO

Lista subgrupos de un grupo principal.

List subgroups of parent group "group-id-123" in "master" realm, limit 10

list-group-members ⭐ NUEVO

Lista miembros de un grupo.

List all members of group "group-id-123" in "master" realm, limit 20

🔗 Herramientas de Gestión de Proveedores de Identidad ⭐ NUEVO

create-identity-provider

Crea un nuevo proveedor de identidad para integración SSO.

Create SAML identity provider "company-saml" in "master" realm with SSO URL and certificate

update-identity-provider

Actualiza un proveedor de identidad existente.

Update identity provider "company-saml" in "master" realm to change display name

delete-identity-provider

Elimina un proveedor de identidad.

Delete identity provider "old-saml" from "master" realm

list-identity-providers

Lista todos los proveedores de identidad en un dominio.

List all identity providers in "master" realm

get-identity-provider

Obtiene detalles de un proveedor de identidad específico.

Get details for identity provider "company-saml" in "master" realm

create-identity-provider-mapper

Crea un mapeador para proveedor de identidad (mapeo de usuario externo).

Create user attribute mapper for identity provider "company-saml" in "master" realm

update-identity-provider-mapper

Actualiza un mapeador de proveedor de identidad.

Update mapper "mapper-id-123" for identity provider "company-saml" in "master" realm

📊 Herramientas de Gestión de Sesiones y Eventos

list-sessions

Lista todas las sesiones activas en un dominio.

List all active sessions in "master" realm

get-user-sessions

Lista sesiones activas para un usuario específico.

Get active sessions for user "user-id-123" in "master" realm

list-events

Recupera eventos de autenticación y administración.

List last 10 events in "master" realm

clear-events

Limpia registros de eventos.

Clear all events in "master" realm

🧪 Pruebas y Desarrollo

Pruebas con MCP Inspector

npx @modelcontextprotocol/inspector npx keycloak-mcp-server

Visite http://localhost:6274 para probar las más de 80 herramientas de forma interactiva.

Desarrollo Local

npm run watch    # Auto-rebuild on changes
npm run dev     # Test server directly

Pruebas de Estrés

El servidor ha sido sometido a pruebas de estrés con más de 80 operaciones consecutivas sin fallos de autenticación, lo que demuestra una confiabilidad de nivel de producción.

🔧 Arquitectura

Sistema de Autenticación a Prueba de Fallos

• Instancias de Cliente Nuevas: Crea un nuevo KcAdminClient para cada solicitud
• Lógica de Reintento: Retroceso exponencial con un máximo de 2 intentos
• Gestión de Conexiones: Tiempo de espera de 15 segundos con limpieza adecuada
• Manejo de Errores: Mensajes de error integrales para todos los escenarios

Implementación en TypeScript

• Seguridad de Tipos: Cobertura completa de TypeScript con interfaces adecuadas
• Manejo de Errores: Mensajes de error detallados y registro
• Diseño Modular: Separación clara de responsabilidades

📈 Listo para Producción

Este paquete ha sido extensamente probado y validado:

• ✅ Más de 80 operaciones consecutivas sin fallos de autenticación
• ✅ Operaciones entre reinos funcionando sin problemas
• ✅ Ejecución paralela de herramientas compatible
• ✅ Consultas de búsqueda complejas con múltiples filtros
• ✅ Recuperación de errores y registro detallado
• ✅ Compilación de TypeScript con cero errores
• ✅ Cobertura completa de la API de Keycloak con gestión de organizaciones

🎯 Problema de Organización JWT Resuelto

Este paquete aborda específicamente el problema común de organización JWT:

• ✅ Atributos de Usuario: Almacenar datos de organización en atributos de usuario
• ✅ Mapeadores de Protocolo: Crear mapeadores para incluir la organización en tokens JWT
• ✅ Ámbitos de Cliente: Gestionar ámbitos de token para reclamaciones de organización
• ✅ Organizaciones: Gestión completa del ciclo de vida de la organización
• ✅ Atributos de Grupo: Almacenar metadatos de organización en grupos

Ejemplo de flujo de trabajo:

1. Crear organización usando create-organization
2. Establecer atributo de organización de usuario usando set-user-attributes
3. Crear mapeador de protocolo usando create-protocol-mapper para incluir la organización en JWT
4. Agregar usuario a la organización usando add-organization-member

🔒 Mejores Prácticas de Seguridad

• Usar variables de entorno para credenciales
• Habilitar HTTPS para instancias de Keycloak en producción
• Usar contraseñas de administrador seguras
• Rotar credenciales regularmente
• Monitorear eventos y sesiones de administrador

🤝 Contribuciones

1. Hacer un fork del repositorio
2. Crear una rama de características: git checkout -b feature/amazing-feature
3. Confirmar cambios: git commit -m 'Add amazing feature'
4. Empujar a la rama: git push origin feature/amazing-feature
5. Abrir una solicitud de extracción

📄 Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.

🆘 Soporte

• Problemas de GitHub: Crear un problema
• Documentación: Consulte este README para ejemplos completos
• Documentación de MCP: Model Context Protocol

🔗 Proyectos Relacionados

• Claude Desktop - Asistente de IA compatible con MCP
• Cursor AI - Editor de código impulsado por IA con soporte MCP
• Model Context Protocol - Especificación del protocolo
• Keycloak - Gestión de identidad y acceso de código abierto

📊 Estadísticas del Paquete

• Más de 80 Herramientas: Cobertura completa de administración de Keycloak
• Listo para Producción: Extensamente probado y validado
• TypeScript: Seguridad de tipos completa y experiencia de desarrollo moderna
• Multiplataforma: Soporte para Windows, macOS y Linux
• Cero Problemas de Dependencias: Gestión robusta de dependencias
• Gestión de Organizaciones: Resolver problemas de visibilidad de organización JWT
• Características Avanzadas: Mapeadores de protocolo, ámbitos de cliente, proveedores de identidad

---

Hecho con ❤️ para la comunidad de Keycloak y IA