Octodet Keycloak

Administra Key

Documentación

Servidor MCP de Octodet Keycloak

Un potente servidor de Model Context Protocol para la administración de Keycloak, que proporciona un conjunto completo de herramientas para gestionar usuarios, realms, roles y otros recursos de Keycloak a través de interfaces LLM.

Características

Gestión de Usuarios: Crear, eliminar y listar usuarios en todos los realms
Administración de Realms: Capacidades integrales de gestión de realms
Integración Segura: Autenticación con credenciales de administrador
Configuración Sencilla: Configuración simple con variables de entorno
Integración LLM: Uso fluido con Claude, ChatGPT y otros asistentes de IA compatibles con MCP

Instalación

Vía NPM (Recomendado)

El servidor está disponible como paquete NPM:

# Direct usage with npx
npx -y @octodet/keycloak-mcp

# Or global installation
npm install -g @octodet/keycloak-mcp

Configuración

Variables de Entorno

Variable	Descripción	Valor por Defecto
KEYCLOAK_URL	URL del servidor Keycloak	http://localhost:8080
KEYCLOAK_ADMIN	Nombre de usuario administrador	admin
KEYCLOAK_ADMIN_PASSWORD	Contraseña del administrador	admin
KEYCLOAK_REALM	Realm por defecto	master

Configuración del Cliente MCP

VS Code

Añade esto a tu 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

Configúralo en tu archivo de configuración de 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 conjunto completo de herramientas MCP para la administración de Keycloak. Cada herramienta está diseñada para realizar tareas administrativas específicas en realms, usuarios y roles.

📋 Resumen de Herramientas

Herramienta	Categoría	Descripción
`create-user`	Gestión de Usuarios	Crear un nuevo usuario en un realm especificado
`delete-user`	Gestión de Usuarios	Eliminar un usuario existente de un realm
`list-users`	Gestión de Usuarios	Listar todos los usuarios en un realm especificado
`list-realms`	Gestión de Realms	Listar todos los realms disponibles
`list-roles`	Gestión de Roles	Listar todos los roles para un cliente específico
`update-user-roles`	Gestión de Roles	Añadir o eliminar roles de cliente para un usuario

👥 Gestión de Usuarios

`create-user`

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

Parámetros Requeridos:

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

Parámetros Opcionales:

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

Estructura del Objeto de Credenciales:

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

Ejemplo de Uso:

{
  "realm": "my-app-realm",
  "username": "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 del usuario creado y un mensaje de confirmación.

`delete-user`

Elimina permanentemente un usuario del realm especificado. Esta acción no se puede deshacer.

Parámetros Requeridos:

realm (cadena): Nombre del realm 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 exitosa.

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

`list-users`

Recupera una lista de todos los usuarios en el realm especificado con su información básica.

Parámetros Requeridos:

realm (cadena): Nombre del realm de destino

Ejemplo de Uso:

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

Respuesta: Devuelve una lista formateada que muestra nombres de usuario e IDs de usuario para todos los usuarios del realm.

🏛️ Gestión de Realms

`list-realms`

Recupera todos los realms disponibles en la instancia de Keycloak.

Parámetros: No se requieren

Ejemplo de Uso:

{}

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

Casos de Uso:

Descubrir realms disponibles
Validar nombres de realms antes de otras operaciones
Visión general administrativa de la configuración de Keycloak

🔐 Gestión de Roles

`list-roles`

Lista todos los roles definidos para un cliente específico dentro de un realm. Útil para comprender los permisos y roles disponibles antes de la asignación.

Parámetros Requeridos:

realm (cadena): Nombre del realm 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: Puedes usar tanto el ID legible del cliente como su identificador UUID.

`update-user-roles`

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

Parámetros Requeridos:

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

Parámetros Opcionales:

rolesToAdd (matriz): Lista de nombres de roles para asignar al usuario
rolesToRemove (matriz): Lista de nombres de roles para eliminar del usuario

Ejemplo de Uso - Añadir Roles:

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

Ejemplo de Uso - Eliminar 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:

Debe proporcionarse al menos uno de rolesToAdd o rolesToRemove
Los roles inexistentes se omiten con advertencias
La operación es atómica por lista de roles (todo o nada para cada tipo de operación)

🚀 Consejos de Uso

IDs de Usuario vs Nombres de Usuario: La mayoría de las operaciones requieren IDs de usuario (UUIDs), no nombres de usuario. Usa list-users para encontrar el ID de usuario correcto.
Identificación de Clientes: El parámetro clientId acepta tanto IDs de cliente legibles como identificadores UUID.
Validación de Realms: Verifica siempre los nombres de realms usando list-realms antes de realizar operaciones.
Descubrimiento de Roles: Usa list-roles para descubrir roles disponibles antes de intentar asignaciones de roles.
Manejo de Errores: Todas las herramientas proporcionan mensajes de error detallados para solucionar problemas de autenticación, permisos o parámetros.

Desarrollo

Configuración de tu Entorno de Desarrollo

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Start the development server with watch mode
npm run watch

Añadir Nuevas Herramientas

Para añadir una nueva herramienta al servidor:

Define el esquema de la herramienta en src/index.ts usando Zod
Añade la definición de la herramienta al manejador ListToolsRequestSchema
Implementa el manejador de la herramienta en la declaración switch de CallToolRequestSchema
Actualiza este README para documentar la nueva herramienta

Pruebas

Usando MCP Inspector

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

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

Pruebas de Integración

Para probar con una instancia local de Keycloak:

# Start Keycloak with Docker
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

# In another terminal, run the MCP server
npm run build
node build/index.js

Despliegue

Paquete NPM

Este proyecto se publica en NPM bajo @octodet/keycloak-mcp.

Despliegue Automatizado

Este proyecto utiliza GitHub Actions para CI/CD 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 - consulta el archivo LICENSE para más detalles.

Autor

Octodet - Construyendo herramientas inteligentes para desarrolladores