Osquery MCP Server

Created By

kousen6 months ago

MCP wrapper for osquery

Content

Osquery MCP Server

A Spring Boot application that provides a Model Context Protocol (MCP) server interface for Osquery, enabling AI assistants to answer system diagnostic questions using natural language.

Overview

The Osquery MCP Server acts as an intelligent bridge between AI models and your operating system. It translates natural language questions like "Why is my fan running so hot?" or "What's using all my memory?" into precise Osquery SQL queries, giving AI assistants the ability to diagnose system issues, monitor performance, and investigate security concerns.

Features

Natural Language System Diagnostics: Ask questions like "What's using my CPU?" and get intelligent answers
8 Specialized Tools for common diagnostic scenarios:
- Execute custom Osquery SQL queries
- Get table schemas and available columns
- Find high CPU/memory usage processes
- Analyze network connections
- Check system temperature and fan speeds (macOS)
- Access example queries for common problems
Smart Query Assistance: Built-in examples and schema discovery help the AI construct better queries
STDIO-based MCP Integration: Works seamlessly with Claude Desktop and other MCP-compatible AI tools
Spring Boot 3.5 with Java 21: Modern, efficient, and maintainable codebase
Comprehensive Testing: Includes automated tests with debug logging support

Prerequisites

Java 21 or higher
Osquery installed and osqueryi available in your PATH
Gradle (or use the included Gradle wrapper)

Installation

Clone the repository:

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

Build the project:

./gradlew build

Run the application:

./gradlew bootRun

Usage

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

Core Tools

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

Diagnostic Tools

getHighCpuProcesses(): Find processes consuming the most CPU
getHighMemoryProcesses(): Find processes using the most memory
getNetworkConnections(): Show active network connections with process info
getTemperatureInfo(): Get system temperature and fan speeds (macOS)

Helper Tools

getCommonQueries(): Get example queries for common diagnostic scenarios

Example AI Interactions

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

"Why is my computer running slowly?" → AI uses getHighCpuProcesses() and getHighMemoryProcesses()

"What's connecting to the internet?" → AI uses getNetworkConnections()

"Why is my fan so loud?" → AI uses getTemperatureInfo() to check system temps

"Show me all Chrome processes" → AI uses executeOsquery() with schema discovery

Configuration

The application is configured through src/main/resources/application.properties:

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

MCP Integration

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

Example MCP Configuration

For Claude Desktop, add to your configuration:

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

Security Considerations

⚠️ Warning: This server executes system commands with the privileges of the running user. Consider the following security measures:

Run with minimal required privileges
Implement query filtering or whitelisting in production
Monitor and log all executed queries
Consider using read-only Osquery queries

Development

Project Structure

├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/kousenit/osquerymcpserver/
│   │   │       ├── OsqueryMcpServerApplication.java
│   │   │       └── OsqueryService.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
│       └── java/
└── build.gradle.kts

Running Tests

./gradlew test

Built-in Diagnostic Queries

The server includes pre-built queries for common diagnostic scenarios. Use getCommonQueries() to see all available examples:

Performance Analysis

-- Top CPU consuming processes
SELECT name, pid, uid, 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

Network Analysis

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

System Information

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