Keycloak MCP Server

Servidor MCP de Keycloak

Un servidor integral de Model Context Protocol (MCP) que expone la API REST de Administración de Keycloak como herramientas MCP tipadas. 299 herramientas que cubren todas las categorías de la API.

---

Características

• Cobertura completa de la API: Los 299 endpoints de la API REST de Administración de Keycloak
• Transporte dual: stdio (Claude Code) y SSE (GitHub Copilot, otros clientes MCP)
• Autenticación automática: Admite flujos de credenciales de contraseña y de cliente con renovación automática de tokens
• Herramientas de configuración cero: Cada herramienta se autodescribe con esquemas de entrada completos

Categorías de la API

Categoría	Herramientas
Detección de Ataques	3
Gestión de Autenticación	38
Certificados de Cliente	6
Acceso Inicial de Cliente	3
Política de Registro de Clientes	1
Mapeos de Roles de Cliente	10
Ámbitos de Cliente	10
Clientes	33
Componentes	6
Grupos	11
Proveedores de Identidad	15
Claves	2
Organizaciones	13
Mapeadores de Protocolo	14
Administración de Reinos	37
Roles	28
Roles por ID	10
Mapeos de Ámbitos	29
Usuarios	30
Total	299

Demostración

(¡Agrega un GIF o captura de pantalla aquí mostrando 3 indicaciones reales y sus herramientas ejecutadas!)

Instalación

Opción 1: Ejecutar directamente con uvx (Recomendado)

Puedes ejecutar el servidor directamente sin instalación manual usando uv de astral:

uvx keycloak-mcp-server

(Al usar uvx, puedes pasar variables de entorno en línea o mantenerlas en tu archivo de configuración MCP).

Opción 2: Instalar vía pip

Si prefieres una instalación global o en un entorno virtual:

pip install git+https://github.com/paoloamato2/keycloak-mcp-server.git

Opción 3: Instalar desde el código fuente (Para desarrollo)

git clone https://github.com/paoloamato2/keycloak-mcp-server.git
cd keycloak-mcp-server
uv pip install -e .

Configuración

Establece variables de entorno (o crea un archivo .env basado en .env.example):

# Required
export KEYCLOAK_URL=http://localhost:8080

# Authentication - Option A: Password flow
export KEYCLOAK_ADMIN_USERNAME=admin
export KEYCLOAK_ADMIN_PASSWORD=admin

# Authentication - Option B: Client credentials flow
export KEYCLOAK_CLIENT_ID=my-client
export KEYCLOAK_CLIENT_SECRET=my-secret

# Optional
export KEYCLOAK_ADMIN_REALM=master    # default: master
export KEYCLOAK_VERIFY_SSL=true       # default: true

Uso

Claude Code (stdio)

Agrega a tu configuración MCP de Claude Code (~/.claude/claude_desktop_config.json o a nivel de proyecto):

{
  "mcpServers": {
    "keycloak": {
      "command": "python",
      "args": ["-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

O si está instalado con uv:

{
  "mcpServers": {
    "keycloak": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/keycloak-mcp-server", "python", "-m", "keycloak_mcp_server"],
      "env": {
        "KEYCLOAK_URL": "http://localhost:8080",
        "KEYCLOAK_ADMIN_USERNAME": "admin",
        "KEYCLOAK_ADMIN_PASSWORD": "admin"
      }
    }
  }
}

GitHub Copilot (SSE)

Inicia el servidor con transporte SSE:

python -m keycloak_mcp_server --transport sse --port 8080

Luego configura en tus ajustes MCP de GitHub Copilot (VS Code settings.json):

{
  "github.copilot.chat.mcpServers": {
    "keycloak": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Línea de Comandos

# stdio mode (default)
python -m keycloak_mcp_server

# SSE mode
python -m keycloak_mcp_server --transport sse --host 0.0.0.0 --port 8080

# Using the entry point
keycloak-mcp-server --transport sse --port 8080

Recomendaciones de Seguridad y Producción

⚠️ ADVERTENCIA DE SEGURIDAD: Este Servidor MCP registra todos los endpoints de la API REST de Administración de Keycloak (299 herramientas), incluyendo operaciones de escritura sensibles (como crear/eliminar usuarios, restablecer contraseñas y gestionar reinos). No uses tus credenciales de superadministrador del reino maestro en un entorno de producción.

Al conectar este servidor MCP a tus Asistentes de IA, sigue estrictamente el Principio de Mínimo Privilegio:

1. Usa Cuentas de Servicio (Flujo de Credenciales de Cliente): Evita usar el flujo de Contraseña (KEYCLOAK_ADMIN_USERNAME / KEYCLOAK_ADMIN_PASSWORD). En su lugar, crea un Cliente de Keycloak dedicado con Cuentas de Servicio Habilitadas, y usa KEYCLOAK_CLIENT_ID y KEYCLOAK_CLIENT_SECRET.

2. Limita los Reinos Destino: No conectes el servidor al reino master a menos que sea específicamente necesario. Apunta KEYCLOAK_ADMIN_REALM al reino exacto que tu asistente de IA debe gestionar.

3. Otorga Solo los Roles Requeridos: Asigna únicamente los roles mínimos necesarios a tu Cuenta de Servicio MCP.

   • Si tu LLM solo necesita leer datos: Asigna solo view-users, view-clients o view-realm.
   • Si tu LLM necesita gestionar usuarios: Asigna solo manage-users.
   • Nunca asignes roles admin o realm-admin a la IA a menos que seas plenamente consciente de los riesgos.

4. Verifica Siempre SSL: Mantén KEYCLOAK_VERIFY_SSL=true habilitado en producción para prevenir ataques de Hombre en el Medio (MITM). Configurarlo en false solo es aceptable para desarrollo local.

Ejemplos

Una vez conectado, puedes usar lenguaje natural para interactuar con Keycloak:

• "Lista todos los reinos" → llama a list_realms
• "Crea un usuario llamado john en el reino maestro" → llama a create_user
• "Muéstrame todos los clientes en el reino de producción" → llama a list_clients
• "¿Qué roles tiene el usuario X?" → llama a get_user_role_mappings
• "Agrega el rol de administrador al grupo de desarrolladores" → llama a add_group_realm_role_mappings

Estructura del Proyecto

src/keycloak_mcp_server/
├── __init__.py          # Package entry point
├── __main__.py          # CLI entry point
├── config.py            # Environment-based configuration
├── client.py            # Async HTTP client with auto-auth
├── server.py            # MCP server setup and tool registration
└── endpoints/           # Endpoint definitions by category
    ├── __init__.py      # Base classes (EndpointDef, Param)
    ├── attack_detection.py
    ├── authentication.py
    ├── certificates.py
    ├── client_initial_access.py
    ├── client_registration_policy.py
    ├── client_role_mappings.py
    ├── client_scopes.py
    ├── clients.py
    ├── component.py
    ├── groups.py
    ├── identity_providers.py
    ├── key.py
    ├── organizations.py
    ├── protocol_mappers.py
    ├── realms.py
    ├── roles.py
    ├── roles_by_id.py
    ├── scope_mappings.py
    └── users.py

Licencia

MIT