MCP Elasticsearch Logs

Servidor MCP pequeno y orientado a produccion para diagnosticar incidencias desde logs en Elasticsearch con esquema desconocido.

Que hace

• Conexion a Elasticsearch con cliente async oficial.
• Descubrimiento dinamico de schema con _field_caps + validacion opcional con documento reciente.
• Tools MCP enfocadas en diagnostico de logs.
• Respuesta normalizada (no devuelve hits crudos como salida principal).

Tools soportadas

• ping
• discover_log_schema
• get_latest_logs
• get_logs_for_service
• get_logs_by_correlation_id
• diagnose_issue

Referencia detallada de cada tool en tools.md.

Variables de entorno

• ELASTICSEARCH_URL (requerida)
• ELASTICSEARCH_API_KEY (opcional, preferida si el cluster usa auth)
• ELASTICSEARCH_USERNAME (opcional)
• ELASTICSEARCH_PASSWORD (opcional)
• ELASTICSEARCH_INDEX_PATTERN (default: logs-*)
• ELASTICSEARCH_VERIFY_CERTS (default: true)
• ELASTICSEARCH_CA_CERTS (opcional)

Reglas de autenticacion:

1. Si existe ELASTICSEARCH_API_KEY, se usa esa.
2. Si no, y existen ELASTICSEARCH_USERNAME + ELASTICSEARCH_PASSWORD, se usa basic auth.
3. Si no hay credenciales, el cliente conecta sin autenticacion.

Como funciona el schema discovery

1. Consulta _field_caps sobre el index pattern configurado.
2. Detecta campos candidatos para timestamp, message, level, service y correlation.
3. Aplica listas ordenadas de prioridad.
4. Si hay sample document, prioriza campos realmente poblados.
5. Devuelve schema parcial (null en lo no encontrado).

Filtro temporal

Se soporta:

• last relativo (15m, 1h, 24h, 7d)
• start/end explicitos (ISO datetime)

Reglas:

• last no se puede combinar con start/end.
• formatos invalidos se rechazan.
• start > end se rechaza.

Ejecucion local

python3.14 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e ".[dev]"

Configura entorno (ejemplo):

cp .env.example .env

Arranque en stdio (default):

mcp-elastic-logs

Arranque en red (streamable-http):

python -m mcp_elastic_logs.server --transport streamable-http --host 0.0.0.0 --port 8093

Ejecucion con Docker

1. Preparar variables:

cp .env.example .env

2. Build de imagen:

docker build -t mcp-elastic-logs:latest .

3. Ejecutar contenedor:

docker run --rm -p 8093:8093 --env-file .env mcp-elastic-logs:latest

Ejecucion con Docker Compose

docker compose up --build

El servicio queda escuchando en http://localhost:8093 con transporte streamable-http.

Entorno de test (Elastic + Kibana + Logstash + MCP)

Tambien tienes un stack de test completo en docker-compose.test.yml, basado en tu plantilla, con un servicio extra seed-logs que carga documentos de ejemplo en logs-test-000001 para poder probar tools inmediatamente.

Arranque:

docker compose -f docker-compose.test.yml up --build

Servicios disponibles:

• Elasticsearch: http://localhost:9200
• Kibana: http://localhost:5601
• MCP server: http://localhost:8093

Nota: este stack de test usa Elasticsearch con seguridad deshabilitada (xpack.security.enabled=false). El MCP puede conectar sin credenciales en ese escenario, asi que el compose de test no necesita valores dummy.

Configuracion de cliente MCP (ejemplo)

{
  "mcpServers": {
    "elastic-logs": {
      "command": "mcp-elastic-logs",
      "env": {
        "ELASTICSEARCH_URL": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "<your-api-key>",
        "ELASTICSEARCH_INDEX_PATTERN": "logs-*",
        "ELASTICSEARCH_VERIFY_CERTS": "false"
      }
    }
  }
}

Documentacion auxiliar

• tools.md: detalle de tools, parametros y comportamiento.
• Agents.md: objetivo del proyecto, stack usado y guia de lectura.