Osquery MCP Server

This project enables AI assistants to answer system diagnostic questions like "Why is my fan running so hot?" or "What's using all my memory?" by translating natural language into Osquery SQL queries.

The stack was upgraded to the latest Spring ecosystem with GraalVM native image support:

GraalVM Native Image: The MCP server compiles to a ~62MB native binary that starts and responds to MCP requests in ~36ms. This is critical for the voice interface use case — when a JavaFX voice client launches the server, it needs to respond instantly.

Virtual Threads:getSystemHealthSummary()now runs all 5 diagnostic queries (CPU, memory, disk, network, temperature) in parallel usingExecutors.newVirtualThreadPerTaskExecutor()withCompletableFuture.supplyAsync(). This reduces response time from the sum of all queries to the duration of the slowest single query.

Jackson 3 Migration(client only): Spring Boot 4 ships Jackson 3 with new Maven coordinates (tools.jackson.coreinstead ofcom.fasterxml.jackson.core), immutable builders (JsonMapper.builder().build()instead ofnew ObjectMapper()), and unchecked exceptions (JacksonExceptioninstead ofJsonProcessingException).

Gradle Build Changes: Spring Boot 4 drops theio.spring.dependency-managementplugin. Dependencies are now managed with Gradle-nativeplatform()BOMs. Spring AI 2.0.0 is GA on Maven Central, so no milestone repository is required.

- Natural Language System Diagnostics: Ask questions like "What's using my CPU?" and get intelligent answers
- 11 Specialized Toolsfor common diagnostic scenarios:

- Execute custom Osquery SQL queries
- Get table schemas and available columns
- Find high CPU/memory/disk I/O usage processes
- Analyze network connections
- Check system temperature and fan speeds (macOS)
- Identify suspicious processes
- Get comprehensive system health summary (parallel execution)
- Access example queries for common problems

- Spring AI Auto-Configuration: Leverages Spring AI 2.0's MCP client starter for zero-configuration setup
- Interactive CLI: REPL interface for exploratory system diagnostics
- Natural Language Processing: Maps human questions to appropriate server tools
- Custom SQL Support: Execute direct osquery commands through the MCP server
- Automatic Tool Discovery: Tools discovered viaSyncMcpToolCallbackProviderinjection
- Built-in Error Handling: Framework-managed timeouts and process management
- Declarative Configuration: YAML-based setup for easy maintenance
- Jackson 3: Uses immutableJsonMapperbuilder pattern and modern APIs
- Comprehensive Testing: Includes automated unit tests for query mapping logic

- Zero Overhead: No server process required - runsosqueryidirectly via Bash
- Natural Language Triggers: Automatically activates for system diagnostic questions
- Predefined Query Templates: Same diagnostic queries as the MCP server
- Baseline Guidance: Includes "is this normal?" context for interpreting results
- Security Explanations: Explains what makes processes suspicious (and common false positives)
- Platform Awareness: Notes macOS vs Linux differences
- Easy Maintenance: Just markdown files - edit and restart Claude Code

- Native Image Startup: ~36ms to first MCP response (vs several seconds for JVM startup)
- Parallel Queries: System health summary runs 5 queries concurrently via virtual threads
- Query Timeouts: Prevents hanging with 30-second timeout for queries, 5-second for version checks
- Process Management: Uses ProcessBuilder for robust resource handling and proper cleanup
- Execution Time Logging: Tracks query performance for monitoring and debugging
- Error Handling: Captures and returns detailed error messages from failed queries
- Resource Safety: Automatically destroys processes that exceed timeout limits

- Java 25+(GraalVM CE 25 recommended for native image support)

- Install via SDKMAN:sdk install java 25.0.2-graalce

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

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

- Build the native image (optional, recommended):

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

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

# 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

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

The server operates in STDIO mode and provides eleven specialized tools for system diagnostics:

The client provides multiple ways to interact with the server:

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\""

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

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

The skill activates automatically when you ask system diagnostic questions in 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?

Option 1: Project-level (included in this repo)

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

Option 2: Personal (works across all projects)

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

The skill guides Claude to runosqueryicommands directly:

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

No server required - Claude executes queries via Bash and interprets the JSON results.

- executeOsquery(sql): Execute any valid Osquery SQL query
- listOsqueryTables(): Get all available Osquery tables on your system
- getTableSchema(tableName): Discover columns and types for any table

- getHighCpuProcesses(): Find processes consuming the most CPU
- getHighMemoryProcesses(): Find processes using the most memory
- getHighDiskIOProcesses(): Find processes with high disk read/write activity
- getNetworkConnections(): Show active network connections with process info
- getTemperatureInfo(): Get system temperature and fan speeds (macOS)
- getSuspiciousProcesses(): Identify processes with unusual characteristics

- getCommonQueries(): Get example queries for common diagnostic scenarios
- getSystemHealthSummary(): Get comprehensive overview of CPU, memory, disk, network, and temperature (runs all queries in parallel via virtual threads)

Instead of writing complex SQL, you can now ask natural language questions:

"Why is my computer running slowly?"-> AI usesgetHighCpuProcesses()andgetHighMemoryProcesses()

"What's connecting to the internet?"-> AI usesgetNetworkConnections()

"Why is my fan so loud?"-> AI usesgetTemperatureInfo()to check system temps

"Show me all Chrome processes"-> AI usesexecuteOsquery()with schema discovery

"Give me an overall system health check"-> AI usesgetSystemHealthSummary()for comprehensive diagnostics (5 queries run in parallel)

"Is my system compromised?"-> AI usesgetSuspiciousProcesses()to check for anomalies

The application is configured throughsrc/main/resources/application.properties:

- Server Name: osquery-server
- Version: 1.0.0
- Mode: SYNC (synchronous operation)
- Transport: STDIO (standard input/output)

This server implements the Model Context Protocol (MCP) using Spring AI's MCP Server starter. It can be integrated with AI tools that support MCP, such as:

- Claude Desktop App
- Other MCP-compatible AI assistants

For Claude Desktop, add to your configuration:

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Create crafted UI components inspired by the best 21st.dev design engineers.

Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server

An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .

MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent

ALAPI MCP Tools,Call hundreds of API interfaces via MCP

AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform

MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references.

APIMatic MCP Server is used to validate OpenAPI specifications using APIMatic. The server processes OpenAPI files and returns validation summaries by leveraging APIMatic’s API.

One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.