Osquery MCP Server

Un servidor MCP para Osquery que permite a los asistentes de IA responder preguntas de diagnóstico del sistema usando lenguaje natural.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Osquery, Cliente y Skill

Una implementación completa para integrar Osquery con asistentes de IA, que ofrece tres enfoques: un servidor MCP para Claude Desktop, un cliente Spring AI y un skill de Claude Code para uso directo desde CLI.

Resumen

Este proyecto permite a los asistentes de IA responder preguntas de diagnóstico del sistema como "¿Por qué mi ventilador está tan caliente?" o "¿Qué está usando toda mi memoria?" traduciendo lenguaje natural a consultas SQL de Osquery.

Tres formas de usar osquery con IA:

Enfoque	Ideal Para	Cómo Funciona
Servidor MCP	Claude Desktop	El servidor Spring Boot se comunica mediante el protocolo MCP
Cliente Spring AI	Acceso programático	Cliente CLI que usa la auto-configuración MCP de Spring AI
Skill de Claude Code	CLI de Claude Code	Ejecución directa de `osqueryi` mediante Bash, sin necesidad de servidor

Novedades

El stack se actualizó al ecosistema Spring más reciente con soporte de imagen nativa GraalVM:

Componente	Anterior	Actual
Spring Boot	3.5.0	4.0.3
Spring AI	1.0.0	2.0.0
Java	21	25 (GraalVM CE)
Jackson	2.x (`com.fasterxml`)	3.x (`tools.jackson`)
Gestión de dependencias	Plugin `io.spring.dependency-management`	BOMs de Gradle `platform()`
Imagen nativa	No soportada	Binario nativo GraalVM (~36ms de arranque)
Salud del sistema	Secuencial (5 consultas)	Paralelo mediante hilos virtuales

Detalles Clave de la Actualización

Imagen Nativa GraalVM: El servidor MCP se compila a un binario nativo de ~62MB que arranca y responde a solicitudes MCP en ~36ms. Esto es crítico para el caso de uso de interfaz de voz: cuando un cliente de voz JavaFX lanza el servidor, necesita responder al instante.

Hilos Virtuales: getSystemHealthSummary() ahora ejecuta las 5 consultas de diagnóstico (CPU, memoria, disco, red, temperatura) en paralelo usando Executors.newVirtualThreadPerTaskExecutor() con CompletableFuture.supplyAsync(). Esto reduce el tiempo de respuesta de la suma de todas las consultas a la duración de la consulta individual más lenta.

Migración a Jackson 3 (solo cliente): Spring Boot 4 incluye Jackson 3 con nuevas coordenadas Maven (tools.jackson.core en lugar de com.fasterxml.jackson.core), builders inmutables (JsonMapper.builder().build() en lugar de new ObjectMapper()) y excepciones no verificadas (JacksonException en lugar de JsonProcessingException).

Cambios en la Compilación con Gradle: Spring Boot 4 elimina el plugin io.spring.dependency-management. Las dependencias ahora se gestionan con BOMs nativos de Gradle platform(). Spring AI 2.0.0 está disponible de forma general en Maven Central, por lo que no se requiere repositorio de hitos.

Características

Servidor MCP

Diagnóstico del Sistema en Lenguaje Natural: Haz preguntas como "¿Qué está usando mi CPU?" y obtén respuestas inteligentes
11 Herramientas Especializadas para escenarios de diagnóstico comunes:
- Ejecutar consultas SQL personalizadas de Osquery
- Obtener esquemas de tablas y columnas disponibles
- Encontrar procesos con alto uso de CPU/memoria/E/S de disco
- Analizar conexiones de red
- Verificar temperatura del sistema y velocidad de ventiladores (macOS)
- Identificar procesos sospechosos
- Obtener resumen completo de salud del sistema (ejecución paralela)
- Acceder a consultas de ejemplo para problemas comunes
Asistencia Inteligente de Consultas: Ejemplos integrados y descubrimiento de esquemas ayudan a la IA a construir mejores consultas
Integración MCP basada en STDIO: Funciona perfectamente con Claude Desktop y otras herramientas de IA compatibles con MCP
Spring Boot 4.0.3 con Java 25: Ecosistema Spring más reciente con soporte de imagen nativa GraalVM
Imagen Nativa GraalVM: Arranque inferior a 200ms para respuestas MCP instantáneas (~36ms medidos)

Cliente Spring AI MCP

Auto-Configuración de Spring AI: Aprovecha el starter de cliente MCP de Spring AI 2.0 para configuración sin pasos adicionales
CLI Interactivo: Interfaz REPL para diagnóstico exploratorio del sistema
Procesamiento de Lenguaje Natural: Mapea preguntas humanas a las herramientas adecuadas del servidor
Soporte de SQL Personalizado: Ejecuta comandos directos de osquery a través del servidor MCP
Descubrimiento Automático de Herramientas: Herramientas descubiertas mediante inyección de SyncMcpToolCallbackProvider
Manejo de Errores Integrado: Timeouts y gestión de procesos administrados por el framework
Configuración Declarativa: Configuración basada en YAML para fácil mantenimiento
Jackson 3: Usa el patrón de builder inmutable JsonMapper y APIs modernas
Pruebas Exhaustivas: Incluye pruebas unitarias automatizadas para la lógica de mapeo de consultas

Skill de Claude Code

Cero Sobrecarga: No requiere proceso de servidor: ejecuta osqueryi directamente mediante Bash
Disparadores de Lenguaje Natural: Se activa automáticamente para preguntas de diagnóstico del sistema
Plantillas de Consulta Predefinidas: Las mismas consultas de diagnóstico que el servidor MCP
Guía de Referencia: Incluye contexto de "¿es esto normal?" para interpretar resultados
Explicaciones de Seguridad: Explica qué hace sospechosos a los procesos (y falsos positivos comunes)
Conciencia de Plataforma: Nota las diferencias entre macOS y Linux
Mantenimiento Fácil: Solo archivos markdown: edita y reinicia Claude Code

Rendimiento y Fiabilidad

Arranque de Imagen Nativa: ~36ms hasta la primera respuesta MCP (frente a varios segundos de arranque JVM)
Consultas Paralelas: El resumen de salud del sistema ejecuta 5 consultas simultáneamente mediante hilos virtuales
Timeouts de Consulta: Evita bloqueos con timeout de 30 segundos para consultas y 5 segundos para verificaciones de versión
Gestión de Procesos: Usa ProcessBuilder para manejo robusto de recursos y limpieza adecuada
Registro de Tiempo de Ejecución: Realiza seguimiento del rendimiento de consultas para monitoreo y depuración
Manejo de Errores: Captura y devuelve mensajes de error detallados de consultas fallidas
Seguridad de Recursos: Destruye automáticamente procesos que exceden los límites de timeout

Requisitos Previos

Java 25+ (GraalVM CE 25 recomendado para soporte de imagen nativa)
- Instalar mediante SDKMAN: sdk install java 25.0.2-graalce
Osquery instalado y osqueryi disponible en tu PATH
Gradle (o usa el wrapper de Gradle incluido)

Instalación

Clona el repositorio:

git clone https://github.com/yourusername/OsqueryMcpServer.git
cd OsqueryMcpServer

Compila el proyecto:

./gradlew build        # Build server + client, run all tests
./gradlew bootJar      # Create executable JAR
cd client-springai && ../gradlew build  # Build Spring AI client

Compila la imagen nativa (opcional, recomendado):

sdk use java 25.0.2-graalce
./gradlew nativeCompile --no-configuration-cache
# Binary at: build/native/nativeCompile/OsqueryMcpServer

Ejecuta el servidor:

# JVM mode
./gradlew bootRun

# Native mode (instant startup)
./build/native/nativeCompile/OsqueryMcpServer

Prueba el cliente Spring AI MCP:

# Natural language queries
cd client-springai && ../gradlew run --args="\"What's using my CPU?\""

# Interactive mode
../gradlew run --args="--interactive"

# Custom SQL queries
../gradlew run --args="\"SELECT name FROM system_info\""

# Run test suite
./test-client-springai.sh

Ejecuta las pruebas:

./gradlew :test                              # Server tests
./gradlew :client-springai:test              # Spring AI client tests
./gradlew build                              # All tests

Uso

Servidor MCP

El servidor opera en modo STDIO y proporciona once herramientas especializadas para diagnóstico del sistema:

Cliente Spring AI MCP

El cliente ofrece múltiples formas de interactuar con el servidor:

Consultas en Lenguaje Natural

cd client-springai
../gradlew run --args="\"What's using my CPU?\""
../gradlew run --args="\"Show network connections\""
../gradlew run --args="\"Why is my fan running?\""
../gradlew run --args="\"Show system health\""
../gradlew run --args="\"Check for suspicious processes\""
../gradlew run --args="\"Show high disk I/O processes\""

Consultas SQL Personalizadas

../gradlew run --args="\"SELECT name, pid, cpu_time FROM processes ORDER BY cpu_time DESC LIMIT 5\""
../gradlew run --args="\"SELECT * FROM system_info\""

Modo Interactivo

../gradlew run --args="--interactive"
# Then type queries interactively, 'help' for assistance, 'exit' to quit

Skill de Claude Code

El skill se activa automáticamente cuando haces preguntas de diagnóstico del sistema en Claude Code:

> Why is my computer slow?
> What's using all my memory?
> Show me network connections
> Are there any suspicious processes?
> Why is my fan running?

Instalación

Opción 1: A nivel de proyecto (incluido en este repositorio)

# Already available in .claude/skills/osquery/ when working in this project

Opción 2: Personal (funciona en todos los proyectos)

cp -r .claude/skills/osquery ~/.claude/skills/
# Restart Claude Code to load the skill

Cómo Funciona

El skill guía a Claude para ejecutar comandos osqueryi directamente:

osqueryi --json "SELECT name, pid, resident_size FROM processes ORDER BY resident_size DESC LIMIT 10"

No se requiere servidor: Claude ejecuta consultas mediante Bash e interpreta los resultados JSON.

Herramientas Disponibles del Servidor

Herramientas Principales

executeOsquery(sql): Ejecuta cualquier consulta SQL válida de Osquery
listOsqueryTables(): Obtén todas las tablas de Osquery disponibles en tu sistema
getTableSchema(tableName): Descubre columnas y tipos para cualquier tabla

Herramientas de Diagnóstico

getHighCpuProcesses(): Encuentra procesos que consumen más CPU
getHighMemoryProcesses(): Encuentra procesos que usan más memoria
getHighDiskIOProcesses(): Encuentra procesos con alta actividad de lectura/escritura de disco
getNetworkConnections(): Muestra conexiones de red activas con información del proceso
getTemperatureInfo(): Obtén temperatura del sistema y velocidad de ventiladores (macOS)
getSuspiciousProcesses(): Identifica procesos con características inusuales

Herramientas Auxiliares

getCommonQueries(): Obtén consultas de ejemplo para escenarios de diagnóstico comunes
getSystemHealthSummary(): Obtén una visión general completa de CPU, memoria, disco, red y temperatura (ejecuta todas las consultas en paralelo mediante hilos virtuales)

Ejemplos de Interacciones con IA

En lugar de escribir SQL complejo, ahora puedes hacer preguntas en lenguaje natural:

"¿Por qué mi computadora va tan lenta?" -> La IA usa getHighCpuProcesses() y getHighMemoryProcesses()

"¿Qué se está conectando a internet?" -> La IA usa getNetworkConnections()

"¿Por qué mi ventilador hace tanto ruido?" -> La IA usa getTemperatureInfo() para verificar temperaturas del sistema

"Muéstrame todos los procesos de Chrome" -> La IA usa executeOsquery() con descubrimiento de esquema

"Dame una verificación general de salud del sistema" -> La IA usa getSystemHealthSummary() para diagnóstico completo (5 consultas en paralelo)

"¿Está comprometido mi sistema?" -> La IA usa getSuspiciousProcesses() para verificar anomalías

Configuración

La aplicación se configura mediante src/main/resources/application.properties:

Nombre del Servidor: osquery-server
Versión: 1.0.0
Modo: SYNC (operación síncrona)
Transporte: STDIO (entrada/salida estándar)

Integración MCP

Este servidor implementa el Protocolo de Contexto de Modelo (MCP) usando el starter de servidor MCP de Spring AI. Se puede integrar con herramientas de IA que soporten MCP, como:

Aplicación de escritorio Claude Desktop
Otros asistentes de IA compatibles con MCP

Ejemplo de Configuración MCP

Para Claude Desktop, añade a tu configuración:

{
  "mcpServers": {
    "osquery": {
      "command": "java",
      "args": ["-jar", "path/to/osquery-mcp-server.jar"]
    }
  }
}

O con el binario nativo para arranque instantáneo (~36ms):

{
  "mcpServers": {
    "osquery": {
      "command": "path/to/OsqueryMcpServer"
    }
  }
}

Consideraciones de Seguridad

Advertencia: Este servidor ejecuta comandos del sistema con los privilegios del usuario que lo ejecuta. Considera las siguientes medidas de seguridad:

Ejecuta con los privilegios mínimos necesarios
Implementa filtrado de consultas o listas blancas en producción
Monitorea y registra todas las consultas ejecutadas
Considera usar consultas de solo lectura de Osquery

Desarrollo

Arquitectura del Proyecto

src/                                    # MCP Server (Spring Boot 4)
├── main/java/com/kousenit/osquerymcpserver/
│   ├── OsqueryMcpServerApplication.java      # Main application
│   └── OsqueryService.java                   # MCP tools (virtual threads)
└── test/java/com/kousenit/osquerymcpserver/
    └── OsqueryServiceTest.java               # Server tests

client-springai/                        # Spring AI 2.0 MCP Client
├── src/main/java/com/kousenit/osqueryclient/springai/
│   └── SpringAiOsqueryClientApplication.java # CLI application (Jackson 3)
├── src/test/java/com/kousenit/osqueryclient/springai/
│   └── QueryMappingTest.java                 # Unit tests
├── application.yml                          # Spring AI configuration
└── test-client-springai.sh                  # Test runner

.claude/skills/osquery/                 # Claude Code Skill
├── SKILL.md                                 # Skill definition & triggers
└── queries.md                               # Query templates & baselines

build.gradle.kts                            # Server build (GraalVM native)

Configuración de Compilación

El proyecto usa Gradle con BOMs de platform() para la gestión de dependencias (Spring Boot 4 elimina el plugin io.spring.dependency-management):

plugins {
    java
    id("org.springframework.boot") version "4.0.3"
    id("org.graalvm.buildtools.native") version "0.10.6"  // Server only
}

dependencies {
    implementation(platform("org.springframework.boot:spring-boot-dependencies:4.0.3"))
    implementation(platform("org.springframework.ai:spring-ai-bom:2.0.0"))
    // ...
}

Ejecución de Pruebas

./gradlew :test                          # Server tests
./gradlew :client-springai:test          # Spring AI client tests
./gradlew build                          # All tests
./test-client-springai.sh                # Full client test suite

Compilación de la Imagen Nativa

# Requires GraalVM CE 25
sdk install java 25.0.2-graalce
sdk use java 25.0.2-graalce

# Build (takes ~25 seconds)
./gradlew nativeCompile --no-configuration-cache

# Test
./build/native/nativeCompile/OsqueryMcpServer

Nota: El flag --no-configuration-cache es necesario debido a una incompatibilidad conocida entre el plugin de herramientas de compilación GraalVM 0.10.6 y la serialización de caché de configuración de Gradle 9.

Consultas de Diagnóstico Integradas

El servidor incluye consultas preconstruidas para escenarios de diagnóstico comunes. Usa getCommonQueries() para ver todos los ejemplos disponibles:

Análisis de Rendimiento

-- Top CPU consuming processes
SELECT name, pid, uid, (user_time + system_time) AS cpu_time FROM processes ORDER BY cpu_time DESC LIMIT 10;

-- Memory usage by process
SELECT name, pid, resident_size, total_size FROM processes ORDER BY resident_size DESC LIMIT 10;

Análisis de Red

-- Active network connections
SELECT pid, local_address, local_port, remote_address, remote_port, state
FROM process_open_sockets WHERE state = 'ESTABLISHED'

Información del Sistema

-- Overall system info
SELECT hostname, cpu_brand, physical_memory, hardware_vendor, hardware_model FROM system_info;

-- Recent file changes
SELECT path, mtime, size FROM file WHERE path LIKE '/Users/%'
AND mtime > (strftime('%s', 'now') - 3600)

La IA puede usar estas como plantillas o llamar directamente a las herramientas de diagnóstico especializadas.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Licencia

Licencia MIT. Consulta Licencia para más detalles.

Agradecimientos

Osquery por Facebook
Spring AI MCP por la implementación del protocolo MCP
Framework Spring Boot
GraalVM por la compilación de imagen nativa