OsqueryMcpServer
MCP wrapper and Claude Code Skill for osquery
claude mcp add --transport stdio kousen-osquerymcpserver docker run -i kousen/osquerymcpserver:latest \ --env JAVA_TOOL_OPTIONS="Placeholders for JVM tuning if needed" \ --env SPRING_PROFILES_ACTIVE="prod"
How to use
OsqueryMcpServer exposes nine diagnostic tools via the MCP protocol to Claude Desktop and compatible MCP clients. The server translates natural language questions into Osquery SQL and returns structured results, enabling system health checks, process discovery, network analysis, and temperature monitoring across supported platforms. You can interact with it through a Spring Boot-based MCP server (via Docker in this setup) or via a compatible MCP client that auto-discovers tools. Typical usage involves asking general diagnostics (e.g., What’s using my CPU?) or issuing direct SQL queries through the MCP client for precise control over osquery queries.
How to install
Prerequisites:
- Docker (to run the MCP server image) or a Java/Gradle development environment if you build from source
- Osquery installed on the host or within the container image
- Basic familiarity with MCP-enabled clients (e.g., Claude Desktop)
Installation via Docker (recommended):
- Ensure Docker is installed and running.
- Pull and run the MCP server image: docker run -i kousen/osquerymcpserver:latest
Alternative: Build from source (requires Java 21+ and Gradle):
- Clone the repository: git clone https://github.com/yourusername/OsqueryMcpServer.git cd OsqueryMcpServer
- Build the project and create a runnable JAR: ./gradlew build ./gradlew bootJar
- Run the server locally (example): java -jar build/libs/osquery-mcp-server-1.0.0.jar
Test and interact with the Spring AI client (if you have it in the repo):
- Build the client: cd client-springai && ../gradlew build
- Run natural language queries: ../gradlew run --args=""What’s using my CPU?""
- Run custom SQL queries: ../gradlew run --args=""SELECT name, pid, cpu_time FROM processes ORDER BY cpu_time DESC LIMIT 5""
Note: If using Docker, ensure environment variables (like Spring profiles) align with your deployment needs.
Additional notes
Tips and common issues:
- Ensure Osquery is installed and osqueryi is accessible in the container or host where the server runs.
- When running in Docker, expose necessary MCP endpoints and configure volume mounts if you need access to host OSquery results.
- The MCP tools include core capabilities like executeOsquery(sql), listOsqueryTables(), and getTableSchema(tableName). Use natural language prompts to map to these tools or craft direct SQL queries for precise control.
- For macOS-specific temperature data (getTemperatureInfo), remember that some fields may be unavailable on non-macOS hosts.
- If you see timeout issues, adjust the server's timeout configuration or ensure the host has sufficient CPU/memory for running osquery queries.
