Servidor Octodet Keycloak MCP

Un potente servidor de Protocolo de Contexto de Modelo para la administración de Keycloak, que proporciona un completo conjunto de herramientas para gestionar usuarios, reinos, roles y otros recursos de Keycloak a través de interfaces LLM.

Características

• Gestión de usuarios: Crear, eliminar y listar usuarios a través de reinos
• Administración dereinos: Capacidades completas de administración de reinos
• Integración segura: Autenticación con credenciales de administrador
• Configuración sencilla: Configuración sencilla con variables de entorno
• Integración LLM: Uso sin problemas con Claude, ChatGPT y otros asistentes de IA compatibles con MCP

Instalación

Mediante NPM (recomendado)

El servidor está disponible como paquete NPM:

# Uso directo con npx npx -y @octodet/keycloak-mcp # O instalación global npm install -g @octodet/keycloak-mcp

Configuración

Variables de entorno

Configuración del cliente MCP

Código VS

Añada esto a su settings.json:

{ "mcp.servers": { "keycloak": { "command": "npx", "args": ["-y", "@octodet/keycloak-mcp"], "env": {"KEYCLOAK_URL": "http://localhost:8080", "KEYCLOAK_ADMIN": "admin", "KEYCLOAK_ADMIN_PASSWORD": "admin" } } }

Claude Desktop

Configure en su archivo de configuración Claude Desktop:

{ "mcpServers": { "keycloak": { "command": "npx", "args": ["-y", "@octodet/keycloak-mcp"], "env": {"KEYCLOAK_URL": "http://localhost:8080", "KEYCLOAK_ADMIN": "admin", "KEYCLOAK_ADMIN_PASSWORD": "admin" } } }

Para desarrollo local

{ "mcpServers": { "keycloak": { "command": "node", "args": ["path/to/build/index.js"], "env": {"KEYCLOAK_URL": "http://localhost:8080", "KEYCLOAK_ADMIN": "admin", "KEYCLOAK_ADMIN_PASSWORD": "admin" } } }

Herramientas disponibles

El servidor proporciona un completo conjunto de herramientas MCP para la administración de Keycloak. Cada herramienta está diseñada para realizar tareas administrativas específicas a través de dominios, usuarios y roles.

resumen de herramientas

gestión de usuarios

crear-usuario

Crea un nuevo usuario en un ámbito especificado con atributos de usuario completos y credenciales opcionales.

Parámetros obligatorios:

• realm (cadena): Nombre del dominio de destino
• username (cadena): Nombre de usuario único para el nuevo usuario
• email (cadena): Dirección de correo electrónico válida
• firstName (cadena): Nombre del usuario
• lastName (cadena): Apellido del usuario

Parámetros opcionales:

• enabled (booleano): Habilitar/deshabilitar cuenta de usuario (por defecto: true)
• emailVerified (booleano): Marcar correo electrónico como verificado
• credentials (matriz): Matriz de objetos de credenciales para establecer contraseñas

Estructura de objetos credenciales:

• type (cadena): Tipo de credencial (por ejemplo, "contraseña")
• value (cadena): El valor de la credencial
• temporal (booleano): Si la contraseña debe cambiarse en el primer inicio de sesión

Ejemplo de uso:

{ "realm": "mi-app-realm", "nombre-de-usuario": "john.doe", "email": "john.doe@company.com", "firstName": "John", "lastName": "Doe", "enabled": true, "emailVerified": true, "credentials": [ { "type": "password", "value": "TempPassword123!", "temporary": true } ] }

Respuesta: Devuelve el ID de usuario creado y el mensaje de confirmación.

delete-user

Elimina permanentemente un usuario del dominio especificado. Esta acción no puede deshacerse.

Parámetros obligatorios:

• realm (cadena): Nombre del dominio de destino
• userId (cadena): Identificador único del usuario a eliminar

Ejemplo de uso:

{ "realm": "my-app-realm", "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c"
}

Respuesta: Mensaje de confirmación de eliminación correcta.

⚠️ Advertencia: Esta operación es irreversible. Asegúrese de tener el ID de usuario correcto antes de ejecutarla.

list-users

Obtiene una lista de todos los usuarios del dominio especificado con su información básica.

Parámetros obligatorios:

• realm (cadena): Nombre del dominio de destino

Ejemplo de uso:

{ "realm": "my-app-realm" }

Respuesta: Devuelve una lista formateada que muestra los nombres de usuario y los ID de usuario de todos los usuarios del dominio.

🏛️ Gestión de dominios

list-realms

Obtiene todos los dominios disponibles en la instancia de Keycloak.

Parámetros: Ninguno requerido

Ejemplo de uso:

{}

Respuesta: Devuelve una lista de todos los nombres de dominio disponibles en la instalación de Keycloak.

Casos de uso:

• Descubrir dominios disponibles
• Validación de nombres de dominio antes de otras operaciones
• Visión general administrativa de la instalación de Keycloak

🔐 Gestión de roles

list-roles

Lista todos los roles definidos para un cliente específico dentro de un reino. Útil para comprender los permisos y roles disponibles antes de asignarlos.

Parámetros obligatorios:

• realm (cadena): Nombre del dominio de destino
• clientId (cadena): ID de cliente o UUID del cliente de destino

Ejemplo de uso:

{ "realm": "my-app-realm", "clientId": "my-application" }

Alternativa con UUID de cliente:

{ "realm": "my-app-realm", "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Respuesta: Devuelve una lista formateada de todos los nombres de roles disponibles para el cliente especificado.

💡 Consejo: Puede utilizar el ID legible por humanos del cliente o su identificador UUID.

update-user-roles

Gestiona las asignaciones de roles de cliente para un usuario. Permite añadir y eliminar roles en una sola operación.

Parámetros obligatorios:

• realm (cadena): Nombre del dominio de destino
• userId (cadena): Identificador único del usuario
• clientId (cadena): Identificador del cliente o UUID

Parámetros opcionales:

• rolesToAdd (array): Lista de nombres de roles a asignar al usuario
• rolesToRemove (matriz): Lista de nombres de roles a eliminar del usuario

Ejemplo de uso - Añadir roles:

{ "reino": "my-app-realm", "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c", "clientId": "my-application", "rolesToAdd": ["admin", "user-manager", "report-viewer"] }

Ejemplo de uso - Eliminación de roles:

{ "realm": "my-app-realm", "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c", "clientId": "my-application", "rolesToRemove": ["temporary-access", "beta-tester"] }

Ejemplo de uso - Operación combinada:

{ "realm": "my-app-realm", "userId": "8f5c21e3-7c9d-4b5a-9f3e-8d4f6a2e7b1c", "clientId": "my-application", "rolesToAdd": ["senior-user"], "rolesToRemove": ["junior-user", "trainee"] }

Respuesta: Resumen detallado de roles añadidos, eliminados y cualquier error encontrado.

notas:

• Se debe proporcionar al menos uno de los rolesToAdd o rolesToRemove
• Los roles no existentes se omiten con advertencias
• La operación es atómica por lista de roles (todos o ninguno para cada tipo de operación)

consejos de uso

1. ID de usuario frente a nombres de usuario: La mayoría de las operaciones requieren IDs de usuario (UUIDs), no nombres de usuario. Utilice list-users para encontrar el ID de usuario correcto.

2. Identificación del cliente: El parámetro clientId acepta tanto identificadores de cliente legibles por humanos como identificadores UUID.

3. Validación dedominio: Compruebe siempre los nombres de dominio utilizando list-realms antes de realizar operaciones.

4. Detección de roles: Utilice list-roles para descubrir los roles disponibles antes de intentar asignarlos.

5. Gestión de errores: Todas las herramientas proporcionan mensajes de error detallados para solucionar problemas de autenticación, permisos o parámetros.

Desarrollo

Configuración del entorno de desarrollo

# Clonar el repositorio git clone <url-del-repositorio> # Instalar dependencias npm install # Iniciar el servidor de desarrollo en modo watch npm run watch

Añadir nuevas herramientas

Para añadir una nueva herramienta al servidor

1. Definir el esquema de la herramienta en src/index.ts usando Zod
2. Añade la definición de la herramienta al manejador ListToolsRequestSchema
3. Implementar el gestor de herramientas en la sentencia switch CallToolRequestSchema
4. Actualiza este README para documentar la nueva herramienta

Probando

Uso del Inspector MCP

El Inspector MCP es una gran herramienta para probar su servidor MCP:

npx -y @modelcontextprotocol/inspector npx -y @octodet/keycloak-mcp

Pruebas de integración

Para probar con una instancia local de Keycloak:

# Iniciar Keycloak con Docker docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev # En otro terminal, ejecutar el servidor MCP npm run build node build/index.js

Despliegue

Paquete NPM

Este proyecto está publicado en NPM bajo @octodet/keycloak-mcp.

Despliegue automatizado

Este proyecto utiliza GitHub Actions for CI/CD para probar y publicar automáticamente en NPM cuando se crea una nueva versión.

Requisitos previos

• Node.js 18 o superior
• Instancia de Keycloak en ejecución

Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

Autor

Octodet - Construyendo herramientas inteligentes para desarrolladores