skycloak-mcp

Servidor oficial de Model Context Protocol para Skycloak (Keycloak gestionado): gestina tus clústeres, reinos, aplicaciones y SSO desde cualquier cliente MCP (Claude Desktop, Clade Code, Cursr).

Status: early release. Tool coverage is growing; see the changelog for what's available.

Quick start

claude mcp add --transport http skycloak https://mcp.skycloak.io

Sin clave API, sin ID de cliente, sin configuración. Tu navegador se abre, inicias sesión en Skycloak y las herramientas aparecen. Cualquier cliente MCP que hable HTTP transmisible funciona de la misma manera: dale la URL y nada más.

Luego pide algo:

• "¿Cuáles de mis clústeres de Keycloak están atrasados en actualizaciones?"

• "Crea un reino de prueas en el clúster de la UE con inicio de sesión de Google y GitHun."

• "¿Quién fue añadido al reino de producción en la última semana?"

• "Configura un destino SIEM que reenvíe eventos de administración a nuestro webhook de Datadog."

Related MCP server: MCP Authentik

Autenticación y seguridad

• HTTP alojado, con OAuth (sin cedeniales que configurar). Apunta tu cliente a https://mcp.skycloak.io sin cabecera. El servidor responde con 401 y un enlace a su metadato RFC 9728 en /.well-known/oauth-protected-resoruce, el cliente ejecuta el flujo de código de autorización del navegador contra el reino de inicio de sesión de Skycloak, y el token de acceso obtenido se intercambia por una clave API de corta duración y ámbito de espacio de trabajo en la que se ejecuta la sesión. La clave dura una hora y se renueva automáticamente. No se almacena nada en la configuración de tu cliente.

• HTTP alojado, con una clave API. Crea una clave en el panel de Skycloak y envíala como Authorization: Bearer <key> (o API-Key: <key>). Cada solicitud lleva su propia credencial y actúa solo en el espacio de trabajo de esa credencial. El servidor no mantiene estado de sesión, por lo que una solicitud nunca hereda la de otro llamante. Las claves no se verifican antes de su uso: la API de Skycloak es la autoridad, por lo que una clave no válida aparece como 401 en la primera llamada a la herramienta, no en el momento de la conexión.

• Las herramientas se ajustan a tu rol. Con OAuth, la lista de herramientas se reduce a lo que permiten los ámbitos de la sesión, por lo que a un miembro del espacio de trabajo de solo lectura no se le muestran herramientas de escritura que responderían con 403. Con una clave API se registra toda la superficie, porque los ámbitos de una clave no son visibles para el servidor, y una llamada no autorizada aparece como un 403 de la API.

• Stdio local. Ejecuta skycloak-mcp init y aprueba en tu navegador (flujo de autorización de dispositivo OAuth 2.0). Genera una clave API con ámbito de espacio de trabajo, la almacena en tu llavero del sistema operativo y detecta tu espacio de trabajo predeterminado automáticamente (pasa --workspace <id> para seleccionar otro). skycloak-mcp logout elimina la clave almacenada.

• Sin interfaz / CI. Establece la variable de entorno SKYCLOAK_API_KEY (crea una clave en el panel de Skycloak) para omitir el navegador por completo. Siempre tiene prioridad sobre el llavero.

• Las escrituras están controladas por tu credencial, no por una bandera. El servidor alojado en https://mcp.skycloak.io se ejecuta con capacidad de escritura, y lo que realmente puedes cambiar está limitado por los ámbitos de tu clave y tu rol en el espacio de trabajo: un miembro de solo lectura no puede mutar nada, sin importar lo que diga la lista de herramientas. Añade ?readonly=true a la URL para forzar una superficie de herramientas de solo lectura para una sesión. El binario local es al revés y no registra herramientas de escritura a menos que se inicie con --allow-writes.

• Las credenciales del clúster son opt-in. get_cluster_credentials devuelve las credenciales de administrador de Keycloak de un clúster, que un asistente que tenga la clave vería entonces, por lo que init no solicita ese ámbito por defecto. Usa una clave que lo tenga: crea una en el panel, o a través de stdio inicia sesión con skycloak-mcp init --allow-credentials. Sin ello, la herramienta devuelve un 403 que explica ambas rutas.

• Las herramientas destructivas requieren confirmación: eliminar un reino, por ejemplo, necesita un argumento explícito confirm=true.

• Las solicitudes están limitadas según tu plan de Skycloak; en una respuesta 429, el servidor muestra Retry-After.

Tools

129 herramientas: 58 de solo lectura y 71 de escritura. Las herramientas de solo lectura siempre están disponibles. En el servidor alojado, las herramientas de escritura también están registradas y controladas por los ámbitos de tu credencial; el binario local las registra solo cuando se inicia con --allow-writes.

Los nombres de las herramientas llevan un prefijo skycloak_ que la tabla siguiente omite, por lo que list_clusters es skycloak_list_clusters en tu cliente.

Convenciones: las herramientas destructivas (delete_*, uninstall_extension, cancel_cluster_upgrade) requieren confirm=true. create_cluster es asíncrono: consulta get_cluster hasta que el clúster esté available. create_domain devuelve los registros DNS que el cliente debe crear; verify_domain activa una verificación DNS. set_theme_assignment activa un tema personalizado por tipo de tema de Keycloak (una cadena vacía restablece el predeterminado de fábrica). update_cluster_security deja intactos los ajustes de CAPTCHA. La importación/exportación del reino mueve la configuración de un reino y es independiente de create_export, que descarga la base de datos de todo un clúster: ambos son asíncronos, y el archivo del reino siempre está cifrado, por lo que la contraseña utilizada para exportarlo se necesita para importarlo de nuevo. Un reino puede importarse directamente desde una exportación existente (source_export_id) o desde un archivo subido (create_realm_import_upload_url, PUT, luego upload_s3_key); la importación crea un reino y rechaza una colisión de nombres en lugar de sobrescribir, y necesita confirm=true porque trae consigo usuarios y credenciales.

Conexión

Para HTTP alojado, la ruta más simple es OAuth, que no necesita ninguna credencial:

claude mcp add --transport http skycloak https://mcp.skycloak.io

La primera llamada abre tu navegador, apruebas en la página de inicio de sesión de Skycloak y aparecen las herramientas. Si perteneces a más de un espacio de trabajo, nombra el que quieras:

claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"

De lo contrario, crea una clave API en el panel de control de Skycloak y configura tu cliente MCP para enviarla como un token de portador:

claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"

Esto agrega lo siguiente a .claude.json:

{
  "mcpServers": {
    "skycloak": {
      "type": "http",
      "url": "https://mcp.skycloak.io",
      "headers": {
        "Authorization": "Bearer sk_sc_XXX"
      }
    }
  }
}

Para stdio local, inicia sesión una vez, luego apunta tu cliente a skycloak-mcp run:

skycloak-mcp init        # one-time browser sign-in; stores a key in your keychain

Claude Desktop / Cursor (local, stdio):

{
  "mcpServers": {
    "skycloak": {
      "command": "skycloak-mcp",
      "args": ["run", "--transport", "stdio"]
    }
  }
}

Claude Code:

claude mcp add skycloak -- skycloak-mcp run --transport stdio

Para sin interfaz gráfica / CI (sin navegador), omite init y pasa la clave en su lugar: añade "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } a la configuración, o claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio.

Añade --allow-writes solo cuando tengas intención de hacer cambios (inicia sesión con skycloak-mcp init --allow-writes, o usa una clave con alcance de escritura).

Añade ?readonly=true a una URL HTTP alojada para exponer solo herramientas de solo lectura para esa sesión HTTP, o ?readonly=false para solicitar la superficie de herramientas con capacidad de escritura. El parámetro de consulta predeterminado es false, pero las herramientas de escritura se registran solo cuando el servidor se inició con --allow-writes.

Añade ?workspace=<uuid> para elegir sobre qué espacio de trabajo actúa una sesión OAuth. Solo es necesario cuando perteneces a más de uno; con un solo espacio de trabajo el servidor lo elige por ti, y si perteneces a varios y no nombras ninguno, la conexión falla con un mensaje que los enumera.

Ejecución del transporte HTTP

skycloak-mcp run --transport http --http-addr :8080

No necesita credenciales propias: los llamadores proporcionan las suyas por solicitud, por lo que no se inyecta nada en el momento del despliegue. GET /healthz y GET /readyz no están autenticados y solo informan de que el proceso está activo; deliberadamente no consultan la API de Skycloak, por lo que un problema en un servicio ascendente no puede hacer fallar la sonda de todas las réplicas a la vez. El servidor no mantiene estado de sesión, por lo que las réplicas no necesitan afinidad de sesión y pueden escalarse o actualizarse libremente. SIGTERM detiene nuevas conexiones y drena las llamadas en curso.

La ruta OAuth está activa siempre que SKYCLOAK_ISSUER y SKYCLOAK_DASHBOARD_URL estén configuradas, que lo están por defecto. GET /.well-known/oauth-protected-resource se sirve sin autenticación, nombrando el realm como el servidor de autorización. Su valor resource se toma de SKYCLOAK_PUBLIC_URL cuando está configurada, y en caso contrario del Host y esquema de la propia solicitud, por lo que un despliegue de un solo host detrás de un ingress no necesita configuración adicional. El esquema proviene de X-Forwarded-Proto cuando está presente, y en caso contrario por defecto es https para cualquier cosa que no sea un host de bucle local, ya que TLS termina en el upstream y publicar un identificador http:// no coincidiría con la URL a la que se conectó el cliente. Establece SKYCLOAK_PUBLIC_URL si tu ingress reescribe Host. El documento también lista openid profile email como sus scopes_supported, y el desafío WWW-Authenticate los repite como un parámetro scope, por lo que un cliente que lea cualquiera de ellos solicita esos ámbitos al realm: openid es obligatorio, porque el intercambio de tokens hace que el dashboard llame al endpoint userinfo de Keycloak y Keycloak rechaza un token concedido sin él. Un token que llega sin él es rechazado en la verificación con un 401 y el desafío, en lugar de ser llevado a un intercambio que no puede tener éxito, por lo que un cliente que aún tenga una concesión anterior deja de reintentar e inicia sesión de nuevo. Dejar en blanco cualquiera de las variables de issuer o dashboard desactiva OAuth por completo, y el servidor vuelve a desafiar solo con una clave de API.

El inicio registra una línea con el cableado que resolvió (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=), por lo que se puede detectar un despliegue mal configurado sin necesidad de redeploy. Cada solicitud rechazada en la ruta OAuth registra una línea que nombra la etapa que falló (verify, exchange o scopes), el estado que recibió el llamador y el error subyacente. Un fallo de verificación añade la comprobación que rechazó el token (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope, etc.); un fallo de intercambio añade el estado del dashboard y el host llamado. El llamador aparece como el sujeto del token una vez verificado, y nunca como una credencial: el token de acceso, la cabecera Authorization y la clave de API acuñada nunca se registran.

Configuración

Comandos: init (inicio de sesión en navegador), run (servir), logout (eliminar la clave almacenada). init acepta --workspace <id>, --allow-writes, --allow-credentials y --ttl-days (por defecto 90).

Desarrollo

make build      # build the server binary
make test       # unit tests
make run        # run on stdio for local testing
make inspector  # MCP Inspector against the local binary
make lint       # golangci-lint
make generate   # regenerate the API client from the OpenAPI spec

El cliente de API en internal/apiclient se genera a partir de la especificación OpenAPI de Skycloak con oapi-codegen.

Mantenerse sincronizado con la API

El cliente en internal/apiclient se genera a partir de internal/apiclient/openapi.yaml con oapi-codegen; ejecuta make generate para actualizarlo. CI falla si el código generado confirmado se desvía de la especificación. Las solicitudes se reintentan en 429/5xx con retroceso consciente de Retry-After.

Distribución

Publicado como binarios de GitHub y una imagen de contenedor ghcr.io/sky-cloak/skycloak-mcp en cada etiqueta, y publicado en el Registro MCP como io.skycloak/skycloak-mcp. La mayoría de las personas no necesitan ninguno: el servidor alojado no necesita instalación.

Seguridad

Por favor, reporta las vulnerabilidades de forma privada. Consulta SECURITY.md.

Contribuyentes

Construido en Skycloak por Guilliano Molaire, Neville Omangi y Aphilas. El historial del repositorio se comprimió cuando se abrió, por lo que el registro de commits no refleja quién escribió qué.

Licencia

Apache-2.0. La descripción OpenAPI en internal/apiclient/openapi.yaml se genera a partir de la API de la plataforma Skycloak y es (c) Skycloak; se incluye aquí para que el cliente pueda generarse y verificarse. Consulta NOTICE.