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

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Elasticsearch

Solución Mejorada del Servidor MCP de Elasticsearch - Enfoque 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 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
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

Soporte Multi-Versión de Elasticsearch

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

Versión	Estado	Cliente	Notas
ES 5.x	✅	5.6.22	EOL - Solo herramientas básicas
ES 6.x	✅	6.8.8	EOL - ILM disponible (6.6+)
ES 7.x	✅	7.17.14	LTS - Funciones completas
ES 8.x	✅	8.19.1	Recomendado - Últimas funciones, ES\|QL (8.11+)
ES 9.x+	✅	Retroceso automático	Preparado 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

El Marco de Consultas (v0.9.0)

Desde la v0.9.0, el servidor incluye un marco de consultas: una capa determinista entre el modelo de IA y su clúster. La filosofía de diseño es simple:

El modelo dirige; el marco conoce. La intención ("encontrar inicios de sesión fallidos por usuario") pertenece al modelo. La corrección (nombres de campos reales, capacidad de agregación, peculiaridades de versión) pertenece al marco.

Lo que esto significa en la práctica — a nivel de principios, no de detalles internos:

La verdad en vivo supera al conocimiento empaquetado, que supera a la memoria del modelo. Cada consulta se verifica contra las capacidades reales de campos del clúster antes de ejecutarse. Un vocabulario ECS (Esquema Común de Elasticsearch) empaquetado proporciona significado; el clúster en vivo proporciona existencia. La memoria del propio modelo nunca se considera confiable.
Los errores inequívocos se corrigen silenciosamente; los ambiguos se convierten en orientación. El ejemplo clásico: un sufijo .keyword espurio en mapeos ECS modernos se corrige automáticamente (y se informa la corrección); un campo desconocido bloquea la consulta condenada y devuelve los campos reales más cercanos en lugar de un error del proveedor.
El conocimiento de campos permanece fuera de la ventana de contexto. El diccionario ECS completo (miles de campos) reside en la memoria del proceso. El modelo recupera solo el puñado que necesita, bajo demanda, mediante lookup_fields.
Cada fallo debe ser accionable. Los errores crudos de Elasticsearch se reescriben con sugerencias en vivo y consejos sobre nomenclatura de índices (data stream vs. nomenclatura heredada de Beats, índices internos que deben accederse mediante APIs de Kibana, etc.).
El modelo necesita cero conocimiento de versión. Las eras de nomenclatura, las diferencias de API y las diferencias de estilo de mapeo (subcampo heredado text + .keyword vs. keyword simple moderno) son absorbidas completamente por el marco. El mismo modelo se comporta de manera idéntica contra ES 5.6 y ES 9.x — verificado por una matriz de pruebas de versión que cubre nueve versiones de transición (5.6 → 9.0).
Siempre existe una vía de escape. La validación se puede omitir por llamada (skip_lint) cuando el modelo sabe más — por ejemplo, campos de tiempo de ejecución definidos fuera de la consulta. El marco asiste; nunca aprisiona.

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

Instale (o ejecute) el servidor, apúntelo a su clúster mediante variables de entorno, regístrelo en su cliente MCP y luego simplemente inicie una conversación — el servidor se conecta y registra las herramientas que su versión de ES soporta.

Opciones de Configuración

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

Configuración de Elasticsearch

Variable de Entorno	Descripción	Requerido
`ES_URL`	URL de su instancia de Elasticsearch	Sí
`ES_API_KEY`	Clave API de Elasticsearch para autenticación	No
`ES_USERNAME`	Nombre de usuario de Elasticsearch para autenticación básica	No
`ES_PASSWORD`	Contraseña de Elasticsearch para autenticación básica	No
`ES_CA_CERT`	Ruta al certificado CA personalizado para SSL/TLS de Elasticsearch	No
`NODE_TLS_REJECT_UNAUTHORIZED`	Establecer a `0` para desactivar la validación de certificados SSL	No

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

Variable de Entorno	Descripción	Predeterminado	Valores
`MCP_TRANSPORT`	Selección del modo de transporte	`stdio`	`stdio`, `http`
`MCP_HTTP_PORT`	Puerto del servidor HTTP (cuando se usa transporte HTTP)	`3000`	1-65535
`MCP_HTTP_HOST`	Host del servidor HTTP (cuando se usa transporte HTTP)	`localhost`	Cualquier 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)

Instalar globalmente mediante NPM

npm install -g @tocharianou/elasticsearch-mcp

Ejecutar directamente
```
npx @tocharianou/elasticsearch-mcp
```

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

Descargar 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)

Verificar la integridad del paquete

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

Extraer y usar

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

Clonar el repositorio

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

Instalar dependencias
```
npm install
```
Compilar el proyecto
```
npm run build
```

Configurar la aplicación 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"
      }
    }
  }
}

Depuración con MCP Inspector (opcional)

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

Notas de Instalación e Integración

Si npm install -g se comporta mal:

Errores de permisos (EACCES) en la instalación global — no sudo. O bien omita la instalación global por completo y deje que su cliente MCP ejecute npx @tocharianou/elasticsearch-mcp (npx obtiene bajo demanda), o establezca un prefijo a nivel de usuario: npm config set prefix ~/.npm-global y agréguelo a su PATH.
Registro lento o bloqueado — use un espejo solo para la instalación: npm install -g @tocharianou/elasticsearch-mcp --registry=https://registry.npmmirror.com.
Versión de Node — requiere Node 18+ (node --version). Node más antiguo falla al inicio con errores de ESM/fetch, no en el momento de la instalación.
Inicio en frío de npx — la primera ejecución de npx descarga el paquete; si su cliente MCP agota el tiempo de espera en la primera conexión, ejecute npx @tocharianou/elasticsearch-mcp una vez en una terminal para calentar la caché y luego reconéctese.
Hosts completamente sin conexión — use el paquete comprimido de GitHub Release (Opción 2) y apunte su cliente a node /path/to/dist/index.js; no se obtiene nada en tiempo de ejecución.

Claude Desktop — Configuración → Desarrollador → Servidores MCP → Editar Configuración, luego agregue el bloque JSON mostrado arriba. Reinicie la aplicación después de editar; el servidor aparece en la lista de herramientas de una nueva conversación.

Claude Code (CLI) — registre el servidor por proyecto o globalmente:

claude mcp add elasticsearch \
  -e ES_URL=https://your-es:9200 -e ES_API_KEY=your-key \
  -- npx @tocharianou/elasticsearch-mcp

Cualquier otro cliente MCP / integración de plataforma — ejecute en modo HTTP (MCP_TRANSPORT=http, ver más abajo) y apunte el cliente a http://host:port/mcp; esta es la forma recomendada para plataformas contenedorizadas, una instancia de servidor por conexión de clúster.

Higiene de credenciales — las variables de entorno terminan en el archivo de configuración de su cliente en texto plano. Prefiera una clave API de solo lectura y con alcance limitado (ver Control de Acceso de Elasticsearch más abajo) en lugar de credenciales de superusuario.

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 MCP

Cualquier cliente compatible con MCP (o JSON-RPC simple sobre HTTP) puede hablar con el endpoint /mcp: inicialice una vez, mantenga el encabezado mcp-session-id devuelto en solicitudes posteriores de tools/list / tools/call. Use /health para verificaciones de actividad.

Herramientas Disponibles

Herramienta	Descripción	Versión Mínima
`list_indices`	Listar índices con filtro de patrón, filtro de salud, ordenamiento y resumen consciente de tokens	ES 5.x+
`get_mappings`	Obtener mapeos de campos con modos plano/árbol/crudo, filtrado de campos y comparación multi-índice	ES 5.x+
`es_search`	Búsqueda completa de Query DSL con resaltado automático, más validación/corrección automática de campos del marco	ES 5.x+
`lookup_fields`	Encontrar los nombres de campo correctos: vocabulario ECS intersectado con los campos reales del índice	ES 5.x+
`execute_es_api`	Ejecutar cualquier endpoint REST de ES directamente (GET/POST/PUT/DELETE/HEAD)	ES 5.x+
`get_shards`	Información de shards con análisis de salud, detección de problemas y recomendaciones	ES 5.x+
`list_data_streams`	Listar y analizar Data Streams con información de ILM y detalles de índices de respaldo	ES 7.9+
`esql_query`	Ejecutar consultas basadas en tuberías de ES\|QL con validación de campos del marco y salida tabular	ES 8.11+

Las herramientas no compatibles con la versión de su clúster se omiten automáticamente al inicio. es_search y esql_query aceptan skip_lint: true para omitir la validación del marco en casos extremos (por ejemplo, campos de tiempo de ejecución definidos fuera de la consulta).

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 (obligatorio)
params — parámetros posicionales que reemplazan los marcadores ? (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)
skip_lint — omitir la validación de campos del harness (opcional, predeterminado false)

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

Contribuciones

¡Agradecemos las contribuciones de la comunidad! Para obtener detalles sobre cómo contribuir, consulte Directrices de contribución.

Cómo Funciona

El cliente MCP (el modelo de IA) decide qué buscar y llama a una herramienta.
El harness valida la solicitud contra el clúster en vivo — corrigiendo lo que no es ambiguo, bloqueando lo que fallaría y traduciendo errores en orientación.
Los resultados regresan limitados por tokens y preprocesados (destacados, tablas, resúmenes de agregaciones), para que las investigaciones largas permanezcan dentro de los límites de contexto.

Ejemplos de Análisis de Seguridad

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

Detección de Amenazas:

"Analizar intentos de ataques de fuerza bruta en las últimas 24 horas"
"Detectar comportamiento de inicio de sesión anormal y direcciones IP sospechosas en el sistema"
"Identificar patrones de ataques de inyección SQL y solicitudes maliciosas"
"Descubrir firmas de ataques DDoS y anomalías de tráfico en flujos de red"

Análisis de Causa Raíz:

"Rastrear la cadena de ataque completa y el alcance del impacto para incidentes de seguridad específicos"
"Analizar causas raíz y rutas de propagación de fallos del sistema"
"Identificar fuentes de violación de datos e información sensible involucrada"
"Investigar incidentes de abuso de privilegios de usuario con cronología y registros de operaciones"

Inteligencia de Amenazas:

"Crear modelos de aprendizaje automático para detectar ataques de día cero y amenazas desconocidas"
"Establecer líneas base de comportamiento e identificar actividades que se desvían de los patrones normales"
"Analizar niveles de amenaza e historial de ataques de dominios maliciosos y direcciones IP"
"Detectar características de comportamiento y patrones de ataque de Amenazas Persistentes Avanzadas (APT)"

Monitoreo en Tiempo Real:

"Monitorear amenazas activas y ataques en curso en el sistema actual"
"Detectar patrones anormales de acceso a datos y comportamientos de escalada de privilegios"
"Descubrir comunicaciones de red sospechosas y actividades de exfiltración de datos"
"Identificar 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 los 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 de Elasticsearch dedicada 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.