Splunk

Interactúa con Splunk Enterprise/Cloud usando consultas en lenguaje natural.

GitHub
107

Documentación

⚠️ Este proyecto está archivado — usa el servidor MCP oficial de Splunk

¡Gracias a todos los que usaron, marcaron con estrella y bifurcaron este proyecto! 🙏 Comenzó como un esfuerzo de la comunidad para llevar soporte de Model Context Protocol (MCP) a Splunk, mucho antes de que existiera una opción oficial.

Splunk ahora ofrece un servidor MCP de primera parte, totalmente compatible que ha crecido más allá de lo que este proyecto comunitario proporciona. Por favor, migra al servidor oficial:

Este repositorio ahora es de solo lectura / archivado y ya no recibirá actualizaciones. El código a continuación se conserva como referencia histórica. ¡Gracias de nuevo! 🚀

Herramienta Splunk MCP (Model Context Protocol)

Una herramienta basada en FastMCP para interactuar con Splunk Enterprise/Cloud mediante lenguaje natural. Esta herramienta proporciona un conjunto de capacidades para buscar datos de Splunk, gestionar almacenes KV y acceder a los recursos de Splunk a través de una interfaz intuitiva.

Modos de operación

La herramienta opera en tres modos:

  1. Modo SSE (Predeterminado)

    • Comunicación basada en Server-Sent Events
    • Interacción bidireccional en tiempo real
    • Adecuado para clientes MCP basados en web
    • Modo predeterminado cuando no se proporcionan argumentos
    • Acceso a través del endpoint /sse

  2. Modo API

    • Endpoints de API RESTful
    • Acceso a través del prefijo de endpoint /api/v1
    • Iniciar con python splunk_mcp.py api

  3. Modo STDIO

    • Comunicación basada en entrada/salida estándar
    • Compatible con Claude Desktop y otros clientes MCP
    • Ideal para integración directa con asistentes de IA
    • Iniciar con python splunk_mcp.py stdio

Características

  • Búsqueda de Splunk: Ejecutar búsquedas de Splunk con consultas en lenguaje natural
  • Gestión de índices: Listar e inspeccionar índices de Splunk
  • Gestión de usuarios: Ver y gestionar usuarios de Splunk
  • Operaciones de almacén KV: Crear, listar y gestionar colecciones de almacén KV
  • Soporte asíncrono: Construido con patrones async/await para mejor rendimiento
  • Registro detallado: Registro completo con indicadores emoji para mejor visibilidad
  • Configuración SSL: Opciones flexibles de verificación SSL para diferentes requisitos de seguridad
  • Depuración mejorada: Registro detallado de conexiones y errores para solución de problemas
  • Pruebas exhaustivas: Pruebas unitarias que cubren toda la funcionalidad principal
  • Manejo de errores: Manejo robusto de errores con códigos de estado apropiados
  • Cumplimiento SSE: Totalmente compatible con la especificación MCP SSE

Herramientas MCP disponibles

Las siguientes herramientas están disponibles a través de la interfaz MCP:

Gestión de herramientas

  • list_tools
    • Lista todas las herramientas MCP disponibles con sus descripciones y parámetros

Verificación de salud

  • health_check
    • Devuelve una lista de aplicaciones Splunk disponibles para verificar la conectividad
  • ping
    • Endpoint de ping simple para verificar que el servidor MCP está activo

Gestión de usuarios

  • current_user
    • Devuelve información sobre el usuario autenticado actualmente
  • list_users
    • Devuelve una lista de todos los usuarios y sus roles

Gestión de índices

  • list_indexes
    • Devuelve una lista de todos los índices de Splunk accesibles
  • get_index_info
    • Devuelve información detallada sobre un índice específico
    • Parámetros: index_name (cadena)
  • indexes_and_sourcetypes
    • Devuelve una lista completa de índices y sus sourcetypes

Búsqueda

  • search_splunk
    • Ejecuta una consulta de búsqueda de Splunk
    • Parámetros:
      • search_query (cadena): cadena de búsqueda de Splunk
      • earliest_time (cadena, opcional): hora de inicio para la ventana de búsqueda
      • latest_time (cadena, opcional): hora de fin para la ventana de búsqueda
      • max_results (entero, opcional): número máximo de resultados a devolver
  • list_saved_searches
    • Devuelve una lista de búsquedas guardadas en la instancia de Splunk

Almacén KV

  • list_kvstore_collections
    • Lista todas las colecciones del almacén KV
  • create_kvstore_collection
    • Crea una nueva colección de almacén KV
    • Parámetros: collection_name (cadena)
  • delete_kvstore_collection
    • Elimina una colección de almacén KV existente
    • Parámetros: collection_name (cadena)

Endpoints SSE

Cuando se ejecuta en modo SSE, los siguientes endpoints están disponibles:

  • /sse: Devuelve información de conexión SSE en formato text/event-stream

    • Proporciona metadatos sobre la conexión SSE
    • Incluye URL para el endpoint de mensajes
    • Proporciona información de protocolo y capacidades

  • /sse/messages: El endpoint principal de flujo SSE

    • Transmite eventos del sistema como heartbeats
    • Mantiene conexión persistente
    • Envía eventos SSE correctamente formateados

  • /sse/health: Endpoint de verificación de salud para el modo SSE

    • Devuelve información de estado y versión en formato SSE

Manejo de errores

La implementación MCP incluye manejo de errores consistente:

  • Comandos de búsqueda no válidos o solicitudes malformadas
  • Permisos insuficientes
  • Recurso no encontrado
  • Validación de entrada no válida
  • Errores inesperados del servidor
  • Problemas de conexión con el servidor Splunk

Todas las respuestas de error incluyen un mensaje detallado que explica el error.

Instalación

Usando UV (Recomendado)

UV es un instalador y resolvedor de paquetes de Python rápido, escrito en Rust. Es significativamente más rápido que pip y proporciona una mejor resolución de dependencias.

Requisitos previos

Inicio rápido con UV

  1. Clonar el repositorio:

    git clone <repository-url>
cd splunk-mcp

  2. Instalar dependencias con UV:

    # Install main dependencies
uv sync

# Or install with development dependencies
uv sync --extra dev

  3. Ejecutar la aplicación:

    # SSE mode (default)
uv run python splunk_mcp.py

# STDIO mode
uv run python splunk_mcp.py stdio

# API mode
uv run python splunk_mcp.py api

Referencia de comandos UV

# Install dependencies
uv sync

# Install with development dependencies
uv sync --extra dev

# Run the application
uv run python splunk_mcp.py

# Run tests
uv run pytest

# Run with specific Python version
uv run --python 3.11 python splunk_mcp.py

# Add a new dependency
uv add fastapi

# Add a development dependency
uv add --dev pytest

# Update dependencies
uv sync --upgrade

# Generate requirements.txt
uv pip compile pyproject.toml -o requirements.txt

Usando Poetry (Alternativa)

Si prefieres Poetry, aún puedes usarlo:

# Install dependencies
poetry install

# Run the application
poetry run python splunk_mcp.py

Usando pip (Alternativa)

# Install dependencies
pip install -r requirements.txt

# Run the application
python splunk_mcp.py

Modos de operación

La herramienta opera en tres modos:

  1. Modo SSE (Predeterminado)

    • Comunicación basada en Server-Sent Events
    • Interacción bidireccional en tiempo real
    • Adecuado para clientes MCP basados en web
    • Modo predeterminado cuando no se proporcionan argumentos
    • Acceso a través del endpoint /sse

  2. Modo API

    • Endpoints de API RESTful
    • Acceso a través del prefijo de endpoint /api/v1
    • Iniciar con python splunk_mcp.py api

  3. Modo STDIO

    • Comunicación basada en entrada/salida estándar
    • Compatible con Claude Desktop y otros clientes MCP
    • Ideal para integración directa con asistentes de IA
    • Iniciar con python splunk_mcp.py stdio

Uso

Uso local

La herramienta puede ejecutarse en tres modos:

  1. Modo SSE (predeterminado para clientes MCP):
# Start in SSE mode (default)
poetry run python splunk_mcp.py
# or explicitly:
poetry run python splunk_mcp.py sse

# Use uvicorn directly:
SERVER_MODE=api poetry run uvicorn splunk_mcp:app --host 0.0.0.0 --port 8000 --reload
  1. Modo STDIO:
poetry run python splunk_mcp.py stdio

Uso con Docker

El proyecto admite tanto los comandos nuevos docker compose (V2) como los heredados docker-compose (V1). Los ejemplos a continuación usan sintaxis V2, pero ambos son compatibles.

  1. Modo SSE (Predeterminado):
docker compose up -d mcp
  1. Modo API:
docker compose run --rm mcp python splunk_mcp.py api
  1. Modo STDIO:
docker compose run -i --rm mcp python splunk_mcp.py stdio

Pruebas con Docker

El proyecto incluye un entorno de pruebas dedicado en Docker:

  1. Ejecutar todas las pruebas:
./run_tests.sh --docker
  1. Ejecutar componentes de prueba específicos:
# Run only the MCP server
docker compose up -d mcp

# Run only the test container
docker compose up test

# Run both with test results
docker compose up --abort-on-container-exit

Los resultados de las pruebas estarán disponibles en el directorio ./test-results.

Consejos de desarrollo con Docker

  1. Construir imágenes:
# Build both images
docker compose build

# Build specific service
docker compose build mcp
docker compose build test
  1. Ver registros:
# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp
  1. Depuración:
# Run with debug mode
DEBUG=true docker compose up mcp

# Access container shell
docker compose exec mcp /bin/bash

Nota: Si estás usando Docker Compose V1, reemplaza docker compose con docker-compose en los comandos anteriores.

Notas de seguridad

  1. Variables de entorno:
  • Nunca confirmes archivos .env
  • Usa .env.example como plantilla
  • Considera usar secretos de Docker para producción
  1. Verificación SSL:
  • VERIFY_SSL=true recomendado para producción
  • Puede desactivarse para desarrollo/pruebas
  • Configurar mediante variables de entorno
  1. Exposición de puertos:
  • Solo exponer los puertos necesarios
  • Usar red interna de Docker cuando sea posible
  • Considerar la seguridad de la red en producción

Variables de entorno

Configura las siguientes variables de entorno:

  • SPLUNK_HOST: La dirección de tu host de Splunk
  • SPLUNK_PORT: Puerto de gestión de Splunk (predeterminado: 8089)
  • SPLUNK_USERNAME: Tu nombre de usuario de Splunk
  • SPLUNK_PASSWORD: Tu contraseña de Splunk
  • SPLUNK_TOKEN: (Opcional) Token de autenticación de Splunk. Si se establece, se usará en lugar de nombre de usuario/contraseña.
  • SPLUNK_SCHEME: Esquema de conexión (predeterminado: https)
  • VERIFY_SSL: Habilitar/deshabilitar verificación SSL (predeterminado: true)
  • FASTMCP_LOG_LEVEL: Nivel de registro (predeterminado: INFO)
  • SERVER_MODE: Modo de servidor (sse, api, stdio) al usar uvicorn

Configuración SSL

La herramienta proporciona opciones flexibles de verificación SSL:

  1. Modo predeterminado (seguro):
VERIFY_SSL=true
  • Verificación completa del certificado SSL
  • Verificación de nombre de host habilitada
  • Recomendado para entornos de producción
  1. Modo relajado:
VERIFY_SSL=false
  • Verificación de certificado SSL deshabilitada
  • Verificación de nombre de host deshabilitada
  • Útil para pruebas o certificados autofirmados

Pruebas

El proyecto incluye una cobertura de pruebas exhaustiva usando pytest y pruebas de extremo a extremo con un cliente MCP personalizado:

Ejecución de pruebas

Ejecución básica de pruebas:

poetry run pytest

Con informe de cobertura:

poetry run pytest --cov=splunk_mcp