Elasticsearch Security Solution

Un servidor de Elasticsearch enfocado en seguridad y análisis de amenazas. Requiere una licencia válida de Elasticsearch (de prueba, platino o empresarial) para la conexión.

GitHub
8
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Elasticsearch

npm version Downloads Ask DeepWiki

Solución Mejorada del Servidor MCP de Elasticsearch - Enfocada en Seguridad y Análisis de Amenazas

Esta es una solución profesional enfocada en seguridad, mantenida por TocharianOU. Permite una interacción integral con todas las APIs de Elasticsearch, optimizada específicamente para análisis de seguridad, detección de amenazas e investigación de incidentes. Las características incluyen monitoreo avanzado de seguridad, detección de anomalías, caza de amenazas, análisis de causa raíz y capacidades integrales de auditoría.

Características Clave de Seguridad:

  • Detección de amenazas en tiempo real y monitoreo de seguridad
  • Aprendizaje automático avanzado para detección de anomalías
  • Análisis de causa raíz y seguimiento de cadenas de ataque
  • Investigación de incidentes de seguridad y análisis forense
  • Monitoreo de cumplimiento e informes de auditoría

Nota: Esta solución requiere una licencia válida de Elasticsearch (prueba, platino o empresarial) y está diseñada para profesionales de seguridad, equipos SOC y analistas de amenazas.

Conéctese a sus datos de Elasticsearch directamente desde cualquier Cliente MCP (como Claude Desktop) utilizando el Protocolo de Contexto de Modelo (MCP). Interactúe con sus datos de seguridad de Elasticsearch mediante consultas en lenguaje natural para análisis avanzado de amenazas y respuesta a incidentes.

Requisitos Previos

  • Una instancia de Elasticsearch
  • Se requiere una licencia válida de Elasticsearch (prueba, platino o empresarial).
  • Credenciales de autenticación de Elasticsearch (clave API o nombre de usuario/contraseña)
  • Cliente MCP (por ejemplo, Claude Desktop) o cliente HTTP para acceso remoto

⚠️ Este proyecto requiere que su clúster de Elasticsearch tenga una licencia válida. Si no tiene una licencia, puede activar una licencia de prueba como se muestra a continuación.

Soporte Multi-Versión de Elasticsearch

Soporta automáticamente Elasticsearch 5.x - 9.x con detección inteligente de versión:

VersiónEstadoClienteNotas
ES 5.x✅5.6.22Fin de vida - Solo herramientas básicas
ES 6.x✅6.8.8Fin de vida - ILM disponible (6.6+)
ES 7.x✅7.17.14LTS - Funciones completas
ES 8.x✅8.19.1Recomendado - Últimas funciones, ES|QL (8.11+)
ES 9.x+✅Retroceso automáticoPreparado para el futuro

Características Clave:

  • Detección automática de versión - No se necesita configuración manual
  • Selección inteligente de cliente - Carga el cliente correcto para su versión de ES
  • Funciones adaptativas - Desactiva herramientas no compatibles (por ejemplo, Data Streams en ES < 7.9, ES|QL en ES < 8.11)
  • Optimizaciones específicas de versión - Maneja las diferencias de API de manera transparente

Qué sucede:

Connect → Detect ES version → Load matching client → Register compatible tools

Conexión SSL/TLS

Para conectarse a Elasticsearch con un certificado autofirmado o en un entorno de prueba, puede establecer la siguiente variable de entorno:

NODE_TLS_REJECT_UNAUTHORIZED=0

⚠️ Esto desactiva la validación de certificados SSL de Node.js. Úselo solo en entornos de desarrollo o pruebas. Para producción, use siempre un certificado CA de confianza.

Instalación y Configuración

  1. Inicie una Conversación
    • Abra una nueva conversación en su Cliente MCP
    • El servidor MCP debería conectarse automáticamente
    • Ahora puede hacer preguntas sobre sus datos de Elasticsearch

Opciones de Configuración

El Servidor MCP de Elasticsearch admite las siguientes opciones de configuración:

Configuración de Elasticsearch

Variable de EntornoDescripciónRequerido
ES_URLURL de su instancia de ElasticsearchSí
ES_API_KEYClave API de Elasticsearch para autenticaciónNo
ES_USERNAMENombre de usuario de Elasticsearch para autenticación básicaNo
ES_PASSWORDContraseña de Elasticsearch para autenticación básicaNo
ES_CA_CERTRuta al certificado CA personalizado para SSL/TLS de ElasticsearchNo
NODE_TLS_REJECT_UNAUTHORIZEDEstablecer en 0 para desactivar la validación de certificados SSLNo

Configuración del Modo de Transporte (NUEVO en v0.3.0)

Variable de EntornoDescripciónPredeterminadoValores
MCP_TRANSPORTSelección del modo de transportestdiostdio, http
MCP_HTTP_PORTPuerto del servidor HTTP (cuando se usa transporte HTTP)30001-65535
MCP_HTTP_HOSTHost del servidor HTTP (cuando se usa transporte HTTP)localhostCualquier host válido

Detalles del Modo de Transporte:

  • Modo Stdio (predeterminado): Para Claude Desktop y clientes MCP locales
  • Modo HTTP Streamable: Se ejecuta como un servidor HTTP independiente para acceso remoto, integración de API y aplicaciones web

Inicio Rápido

Opción 1: Instalación mediante NPM (Recomendada)

  1. Instale globalmente mediante NPM

    npm install -g @tocharianou/elasticsearch-mcp

  2. Ejecute directamente

    npx @tocharianou/elasticsearch-mcp

Opción 2: Lanzamiento de GitHub (Paquete Independiente)

  1. Descargue el paquete de lanzamiento

    • Vaya a Lanzamientos de GitHub
    • Descargue el archivo .tar.gz más reciente y sus archivos de suma de verificación (.sha256 y .sha512)

  2. Verifique la integridad del paquete

    shasum -a 256 -c elasticsearch-mcp-v*.tar.gz.sha256
# Should output: elasticsearch-mcp-v*.tar.gz: OK

  3. Extraiga y use

    mkdir elasticsearch-mcp && cd elasticsearch-mcp
tar -xzf ../elasticsearch-mcp-v*.tar.gz

# Run with your Elasticsearch credentials
ES_URL=https://localhost:9200 ES_API_KEY=your-key node dist/index.js

Opción 3: Instalación desde el Código Fuente

  1. Clone el repositorio

    git clone https://github.com/TocharianOU/elasticsearch-mcp.git
cd elasticsearch-mcp

  2. Instale las Dependencias

    npm install

  3. Compile el Proyecto

    npm run build

  4. Configure la Aplicación de Claude Desktop

    • Abra Claude Desktop App
    • Vaya a Configuración > Desarrollador > Servidores MCP
    • Haga clic en Edit Config y agregue un nuevo Servidor MCP con la siguiente configuración:

    Para Instalación mediante NPM:

    {
  "mcpServers": {
    "elasticsearch-mcp-server": {
      "command": "npx",
      "args": [
        "@tocharianou/elasticsearch-mcp"
      ],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_USERNAME": "elastic",
        "ES_PASSWORD": "your_pass",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

    Para Instalación desde el Código Fuente:

    {
  "mcpServers": {
    "elasticsearch-mcp-server-local": {
      "command": "node",
      "args": [
        "/path/to/your/elasticsearch-mcp/dist/index.js"
      ],
      "env": {
        "ES_URL": "your-elasticsearch-url",
        "ES_USERNAME": "elastic",
        "ES_PASSWORD": "your_pass",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

  5. Depuración con MCP Inspector

    ES_URL=your-elasticsearch-url ES_USERNAME=elastic ES_PASSWORD=your_pass npm run inspector

    Esto iniciará el MCP Inspector, permitiéndole depurar y analizar solicitudes. Debería ver:

    Starting MCP inspector...
Proxy server listening on port 3000

MCP Inspector is up and running at http://localhost:5173

Método 3: Modo HTTP Streamable (NUEVO en v0.3.0)

Ejecute el servidor como un servicio HTTP independiente para acceso remoto e integración de API:

# Start HTTP server (default port 3000)
MCP_TRANSPORT=http \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

# Or with custom port and host
MCP_TRANSPORT=http \
MCP_HTTP_PORT=9000 \
MCP_HTTP_HOST=0.0.0.0 \
ES_URL=your-elasticsearch-url \
ES_USERNAME=elastic \
ES_PASSWORD=your_pass \
npx @tocharianou/elasticsearch-mcp

Características del Modo HTTP Streamable:

  • Expone el servidor MCP en el endpoint http://host:port/mcp
  • Verificación de salud disponible en http://host:port/health
  • Gestión de conexiones basada en sesiones
  • Admite tanto POST (solicitudes JSON-RPC) como GET (flujos SSE)
  • Compatible con cualquier cliente HTTP o SDK de MCP

Ejemplo de uso con cliente HTTP:

// Initialize connection
const response = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'initialize',
    params: {
      protocolVersion: '2024-11-05',
      capabilities: {},
      clientInfo: { name: 'my-client', version: '1.0.0' }
    },
    id: 1
  })
});

const sessionId = response.headers.get('mcp-session-id');

// Subsequent requests include session ID
const toolsResponse = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/list',
    params: {},
    id: 2
  })
});

// Call a tool (e.g., list_indices)
const indicesResponse = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: {
      name: 'list_indices',
      arguments: {}
    },
    id: 3
  })
});

Herramientas Disponibles

HerramientaDescripciónVersión Mínima
list_indicesLista índices con filtro de patrón, filtro de salud, ordenamiento y resumen consciente de tokensES 5.x+
get_mappingsObtiene mapeos de campos con modos plano/árbol/bruto, filtrado de campos y comparación multi-índiceES 5.x+
es_searchBúsqueda completa con Query DSL y resaltado automático en campos de texto/vectoresES 5.x+
execute_es_apiEjecuta cualquier endpoint REST de ES directamente (GET/POST/PUT/DELETE/HEAD)ES 5.x+
get_shardsInformación de shards con análisis de salud, detección de problemas y recomendacionesES 5.x+
list_data_streamsLista y analiza Data Streams con información de ILM y detalles de índices subyacentesES 7.9+
esql_queryEjecuta consultas ES|QL basadas en tuberías con salida tabular y soporte de parámetrosES 8.11+

Las herramientas no compatibles con la versión de su clúster se omiten automáticamente al inicio.

Herramienta de Consulta ES|QL (esql_query)

ES|QL es el lenguaje de consulta moderno basado en tuberías de Elasticsearch, ideal para análisis y exploración de datos sin JSON DSL complejo.

Consultas de ejemplo:

FROM logs-* | WHERE level == "error" | STATS count = COUNT(*) BY service | SORT count DESC | LIMIT 20
FROM metrics-* | WHERE @timestamp > NOW() - 1 hour | STATS avg_cpu = AVG(cpu.usage) BY host.name
FROM auditbeat-* | WHERE event.action == "user_login" AND event.outcome == "failure" | LIMIT 50

Parámetros:

  • query — la cadena ES|QL (requerido)
  • params — parámetros posicionales que reemplazan los marcadores de posición ? (opcional)
  • include_types — incluir información de tipo de columna en la salida (opcional, predeterminado false)
  • break_token_rule — omitir el límite de tokens para resultados grandes (opcional, predeterminado false)

Se registra automáticamente solo en clústeres ES 8.11+.

Contribuciones

¡Damos la bienvenida a contribuciones de la comunidad! Para detalles sobre cómo contribuir, consulte las Pautas de Contribución.

Cómo Funciona

  1. El Cliente MCP analiza su solicitud y determina qué operaciones de Elasticsearch se necesitan.
  2. El servidor MCP se comunica con ES.
  3. El Cliente MCP procesa los resultados y los presenta en un formato fácil de usar, incluyendo resaltados, resúmenes de agregaciones e información de anomalías.

Ejemplos de Análisis de Seguridad

[!TIP] Aquí hay consultas enfocadas en seguridad que puede probar con su Cliente MCP.

Detección de Amenazas:

  • "Analice intentos de ataques de fuerza bruta en las últimas 24 horas"
  • "Detecte comportamientos de inicio de sesión anormales y direcciones IP sospechosas en el sistema"
  • "Identifique patrones potenciales de ataques de inyección SQL y solicitudes maliciosas"
  • "Descubra firmas de ataques DDoS y anomalías de tráfico en flujos de red"

Análisis de Causa Raíz:

  • "Trace la cadena de ataque completa y el alcance del impacto para incidentes de seguridad específicos"
  • "Analice las causas raíz y las rutas de propagación de fallas del sistema"
  • "Identifique fuentes de violación de datos e información sensible involucrada"
  • "Investigue incidentes de abuso de privilegios de usuarios con línea de tiempo y registros de operaciones"

Inteligencia de Amenazas:

  • "Cree modelos de aprendizaje automático para detectar ataques de día cero y amenazas desconocidas"
  • "Establezca líneas base de comportamiento e identifique actividades que se desvían de los patrones normales"
  • "Analice los niveles de amenaza y el historial de ataques de dominios maliciosos y direcciones IP"
  • "Detecte características de comportamiento y patrones de ataque de Amenazas Persistentes Avanzadas (APT)"

Monitoreo en Tiempo Real:

  • "Monitoree amenazas activas y ataques en curso en el sistema actual"
  • "Detecte patrones anormales de acceso a datos y comportamientos de escalada de privilegios"
  • "Descubra comunicaciones de red sospechosas y actividades de exfiltración de datos"
  • "Identifique causas de seguridad del consumo anormal de recursos del sistema y degradación del rendimiento"

Mejores Prácticas de Seguridad

[!WARNING] Evite usar privilegios de administrador del clúster. Cree claves API dedicadas con alcance limitado y aplique control de acceso de grano fino a nivel de índice para prevenir el acceso no autorizado a datos.

Verificación de Integridad del Paquete

Al descargar paquetes de lanzamiento, verifique siempre las sumas de verificación para garantizar la integridad:

# Verify SHA256 checksum
shasum -a 256 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha256

# Verify SHA512 checksum
shasum -a 512 -c elasticsearch-mcp-vX.Y.Z.tar.gz.sha512

Esto protege contra:

  • Descargas corruptas
  • Paquetes manipulados
  • Ataques de intermediario (man-in-the-middle)

Control de Acceso a Elasticsearch

Puede crear una clave API dedicada de Elasticsearch con permisos mínimos para controlar el acceso a sus datos:

{
  "name": "es-mcp-server-access",
  "role_descriptors": {
    "mcp_server_role": {
      "cluster": [
        "monitor"
      ],
      "indices": [
        {
          "names": [
            "index-1",
            "index-2",
            "index-pattern-*"
          ],
          "privileges": [
            "read",
            "view_index_metadata"
          ]
        }
      ]
    }
  }
}

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0.

Solución de Problemas

  • Asegúrese de que su configuración de MCP sea correcta.
  • Verifique que su URL de Elasticsearch sea accesible desde su máquina.
  • Compruebe que sus credenciales de autenticación (clave API o nombre de usuario/contraseña) tengan los permisos necesarios.
  • Si usa SSL/TLS con una CA personalizada, verifique que la ruta del certificado sea correcta y que el archivo sea legible.
  • Revise la salida del terminal para ver mensajes de error.

Si encuentra problemas, no dude en abrir un issue en el repositorio de GitHub.

Ejecución con una Licencia de Prueba

Si su clúster de Elasticsearch no tiene una licencia válida, puede activar una licencia de prueba de 30 días con el siguiente comando:

curl -X POST -u elastic:your_password \
  -k "https://your-es-host:9200/_license/start_trial?acknowledge=true"
  • Reemplace your_password y your-es-host con sus credenciales y host reales.
  • Esto habilitará todas las funciones durante 30 días.

Nota: Este proyecto no se iniciará si su clúster no tiene una licencia válida (prueba, platino, empresarial, etc.).