Servidor MCP de Keycloak

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona una interfaz de lenguaje natural para gestionar la identidad y el acceso de Keycloak a través de su API REST. Este servidor permite a los agentes de IA realizar operaciones de gestión de usuarios, configuración de clientes, administración de reinos y control de acceso basado en roles de forma fluida.

Descripción general

El servidor MCP de Keycloak cierra la brecha entre las aplicaciones de IA y las potentes capacidades de gestión de identidad de Keycloak. Ya sea que esté creando un asistente de IA que necesite gestionar usuarios, configurar clientes o manejar escenarios de autorización complejos, este servidor proporciona las herramientas que necesita mediante comandos sencillos en lenguaje natural.

Related MCP server: Advanced Keycloak MCP server

Características

🔐 Gestión integral de usuarios

Gestione el ciclo de vida de los usuarios desde la creación hasta la eliminación, incluyendo restablecimientos de contraseña, gestión de sesiones y actualizaciones de atributos de usuario.

🏢 Configuración de clientes

Cree y configure clientes OAuth2/OIDC, gestione secretos de cliente y maneje cuentas de servicio mediante programación.

👥 Control de acceso basado en roles

Defina y asigne roles específicos de reino y de cliente, gestione permisos de usuario e implemente un control de acceso detallado.

🏛️ Administración de reinos

Configure los ajustes del reino, gestione grupos predeterminados, maneje configuraciones de eventos y controle políticas en todo el reino.

🔐 Gestión de autenticación

Gestión integral del flujo de autenticación, incluyendo la creación, actualización y eliminación de flujos, gestión de ejecuciones y configuración de autenticadores.

🔄 Gestión de grupos

Organice a los usuarios en grupos, gestione jerarquías de grupos y maneje permisos basados en grupos de manera eficiente.

Instalación

Instalación a través de Smithery

Para instalar mcp-keycloak para Claude Desktop automáticamente a través de Smithery:

npx -y @smithery/cli install mcp-keycloak --client claude

Inicio rápido

Instale usando pip:

pip install mcp-keycloak

Instalación para desarrollo

Clone el repositorio e instale las dependencias:

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak
pip install -e .

Configuración

El servidor se puede configurar mediante variables de entorno o un archivo .env:

# Required configuration
SERVER_URL=https://your-keycloak-server.com
USERNAME=admin-username
PASSWORD=admin-password
REALM_NAME=your-realm

# Optional OAuth2 client configuration
CLIENT_ID=optional-client-id
CLIENT_SECRET=optional-client-secret

Herramientas

El servidor MCP de Keycloak proporciona un conjunto completo de herramientas organizadas por funcionalidad:

Gestión de usuarios

Gestión completa del ciclo de vida del usuario, incluyendo:

• list_users - Listar usuarios con paginación y filtrado

• create_user / update_user / delete_user - Operaciones CRUD completas

• reset_user_password - Gestión de contraseñas

• get_user_sessions / logout_user - Control de sesiones

• count_users - Estadísticas de usuarios

Gestión de clientes

Configuración de clientes OAuth2/OIDC:

• list_clients / get_client / create_client - Operaciones de cliente

• get_client_secret / regenerate_client_secret - Gestión de secretos

• get_client_service_account - Acceso a cuentas de servicio

• update_client / delete_client - Modificaciones de cliente

Gestión de roles

Control de permisos detallado:

• list_realm_roles / create_realm_role - Operaciones de roles de reino

• list_client_roles / create_client_role - Roles específicos de cliente

• assign_realm_role_to_user / remove_realm_role_from_user - Asignaciones de roles

• get_user_realm_roles / assign_client_role_to_user - Consultas de roles de usuario

Gestión de grupos

Organización jerárquica de usuarios:

• list_groups / create_group / update_group - Operaciones de grupo

• get_group_members / add_user_to_group - Gestión de miembros

• get_user_groups / remove_user_from_group - Asociaciones de grupos de usuario

Administración de reinos

Configuración de todo el sistema:

• get_accessible_realms - Lista de reinos accesibles

• get_realm_info / update_realm_settings - Configuración del reino

• get_realm_events_config / update_realm_events_config - Gestión de eventos

• add_realm_default_group / remove_realm_default_group - Ajustes predeterminados

Gestión de autenticación

Control completo del flujo de autenticación:

• list_authentication_flows / get_authentication_flow - Gestión de flujos

• create_authentication_flow / update_authentication_flow - Operaciones CRUD de flujo

• delete_authentication_flow / copy_authentication_flow - Modificaciones de flujo

• get_flow_executions / update_flow_executions - Gestión de ejecuciones

• create_execution / delete_execution - Ciclo de vida de ejecución

• get_authenticator_config / create_authenticator_config - Gestión de configuración

• get_required_actions / update_required_action - Control de acciones requeridas

Uso

Ejecución del servidor

El servidor admite transportes stdio (predeterminado) y HTTP. El archivo de configuración smithery.yaml permite la implementación en la plataforma Smithery y la instalación automática a través de la CLI de Smithery:

# Run in stdio mode (default, for local CLI tools)
python -m src.main

# Run in HTTP mode with streamable HTTP transport
TRANSPORT=http python -m src.main

# Run HTTP mode on a custom port
TRANSPORT=http PORT=8080 python -m src.main

# Or use the convenience script:
./scripts/run_server.sh         # stdio mode (default)
./scripts/run_server.sh http    # HTTP mode
PORT=8080 ./scripts/run_server.sh http  # HTTP mode on custom port

Al usar el transporte HTTP, el servidor será accesible en http://127.0.0.1:8000/mcp/ (o su PUERTO personalizado).

Transporte HTTP

El servidor MCP de Keycloak admite el modo de transporte HTTP, que ofrece varias ventajas:

• Accesibilidad de red: Acceda al servidor desde cualquier máquina de su red

• Múltiples clientes: Admite conexiones simultáneas de múltiples clientes de IA

• Flexibilidad de integración: Fácil integración con aplicaciones web y API

• Equilibrio de carga: Implementación detrás de un proxy inverso para escalabilidad

Detalles del protocolo HTTP

El transporte HTTP sigue la especificación MCP para HTTP transmitible. FastMCP maneja automáticamente todos los requisitos del protocolo:

• Endpoint: Toda la comunicación ocurre a través del endpoint /mcp/

• Método de solicitud: Solicitudes POST con mensajes JSON-RPC 2.0

• Tipos de contenido:

  • El servidor devuelve Content-Type: application/json para respuestas únicas

  • El servidor devuelve Content-Type: text/event-stream para respuestas en streaming

• Cabeceras Accept: Los clientes deben incluir Accept: application/json, text/event-stream

• Formato de mensaje: Todos los mensajes utilizan el formato JSON-RPC 2.0, codificado en UTF-8

FastMCP determina automáticamente si devolver una respuesta JSON única o un flujo SSE según el tipo de solicitud y si la respuesta necesita capacidades de streaming.

Conexión al servidor HTTP

Al ejecutarse en modo HTTP, los clientes pueden conectarse a:

http://127.0.0.1:8000/mcp/

Ejemplo de solicitud de cliente:

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "list_tools", "id": 1}'

Implementación de seguridad

El transporte HTTP implementa todos los requisitos de seguridad de la especificación MCP:

✅ Validación de cabecera Origin (REQUERIDO)

• Valida automáticamente las cabeceras Origin para evitar ataques de rebinding de DNS

• Solo permite conexiones desde orígenes localhost y 127.0.0.1

• Bloquea solicitudes de origen cruzado no autorizadas

✅ Enlace a Localhost (RECOMENDADO)

• Se enlaza solo a 127.0.0.1 para evitar ataques basados en red

• Sigue las recomendaciones de seguridad de la especificación MCP

✅ No se requiere autenticación

• El servidor se ejecuta sin requisitos de autenticación para un desarrollo local simplificado

• Adecuado para uso en localhost y entornos de confianza

Para implementaciones en producción, consideraciones adicionales:

• Utilice HTTPS con certificados adecuados

• Implemente detrás de un proxy inverso (nginx, Apache)

• Establezca reglas de firewall apropiadas

• Implemente autenticación a nivel de proxy inverso si es necesario

Ejemplos de integración

Requisitos previos

Antes de integrar el servidor MCP de Keycloak, asegúrese de tener instalado uno de los siguientes:

• uvx (recomendado): Instale mediante pip install uvx o pipx install uvx

• uv: Siga las instrucciones de instalación

• npm/npx: Para la instalación de Smithery (viene con Node.js)

Opción 1: Uso de la CLI de Smithery (Recomendado)

La forma más fácil: configura todo automáticamente para Claude Desktop:

npx @smithery/cli install @idoyudha/mcp-keycloak --client claude

Este comando le solicitará los valores de configuración necesarios y configurará el servidor automáticamente.

Opción 2: Uso de uvx (Configuración manual)

¡No se requiere clonar! Añada a su claude_desktop_config.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "uvx",
      "args": ["mcp-keycloak"],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

Opción 3: Configuración de desarrollo local

Para desarrollo o personalización:

1. Clone el repositorio:

git clone https://github.com/idoyudha/mcp-keycloak.git
cd mcp-keycloak

2. Añada a su claude_desktop_config.json:

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-keycloak",
        "run",
        "python",
        "-m",
        "src"
      ],
      "env": {
        "SERVER_URL": "https://your-keycloak.com",
        "USERNAME": "admin",
        "PASSWORD": "admin-password",
        "REALM_NAME": "your-realm"
      }
    }
  }
}

💡 Consejos rápidos:

• Reemplace /path/to/mcp-keycloak con la ruta real donde clonó el repositorio

• Asegúrese de que la URL de su servidor Keycloak incluya el protocolo (https:// o http://)

• El REALM_NAME debe coincidir con un reino existente en su instancia de Keycloak

Casos de uso de ejemplo

🤖 Gestión de identidad impulsada por IA

Cree asistentes de IA que puedan manejar la incorporación de usuarios, la gestión de permisos y el control de acceso mediante comandos de lenguaje natural.

🔄 Aprovisionamiento automatizado de usuarios

Cree flujos de trabajo que aprovisionen usuarios automáticamente, asignen roles y configuren aplicaciones cliente según las reglas de negocio.

📊 Análisis de identidad

Consulte y analice datos de usuario, información de sesiones y patrones de acceso para obtener información sobre su infraestructura de identidad.

🚀 Integración DevOps

Integre la gestión de Keycloak en sus pipelines de CI/CD, permitiendo la configuración automatizada de servicios de identidad.

Requisitos

• Python 3.8 o superior

• Servidor Keycloak (probado con Keycloak 18+)

• Acceso de administrador al reino de Keycloak

Licencia

Este proyecto tiene licencia MIT; consulte el archivo LICENSE para obtener más detalles.

Contribución

¡Las contribuciones son bienvenidas! No dude en enviar una solicitud de extracción (Pull Request).

Soporte

Para problemas, preguntas o contribuciones, visite el repositorio de GitHub.