Osquery MCP Server

Osquery MCP 服务、客户端与技能

一套完整的实现方案，可将 Osquery 集成到 AI 助手中，提供三种方式：供 Claude Desktop 使用的 MCP 服务、Spring AI 客户端，以及可直接通过 CLI 使用的 Claude Code 技能。

概述

本项目可让 AI 助手回答“为什么我的风扇这么烫？”或“是什么占用了我所有内存？”等系统诊断问题，方法是将自然语言转换为 Osquery SQL 查询。

将 osquery 与 AI 结合使用的三种方式：

方式	最适合	工作原理
MCP 服务	Claude Desktop	Spring Boot 服务通过 MCP 协议进行通信
Spring AI 客户端	以编程方式访问	使用 Spring AI MCP 自动配置的 CLI 客户端
Claude Code 技能	Claude Code CLI	通过 Bash 直接执行 osqueryi，无需服务

最新动态

技术栈已升级至最新的 Spring 生态系统，并支持 GraalVM 原生镜像：

组件	之前	当前
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）
依赖管理	io.spring.dependency-management 插件	Gradle platform() BOM
原生镜像	不支持	GraalVM 原生二进制文件（启动约需 36ms）
系统健康状况	顺序执行（5 个查询）	通过虚拟线程并行执行

主要升级详情

GraalVM 原生镜像：MCP 服务可编译为约 62MB 的原生二进制文件，启动并响应 MCP 请求仅需约 36ms。这对语音界面使用场景至关重要——当 JavaFX 语音客户端启动服务时，服务需要立即响应。

虚拟线程：getSystemHealthSummary() 现在使用 Executors.newVirtualThreadPerTaskExecutor() 和 CompletableFuture.supplyAsync() 并行运行全部 5 个诊断查询（CPU、内存、磁盘、网络、温度）。这样一来，响应时间从所有查询耗时之和缩短为最慢的单个查询所需的时间。

Jackson 3 迁移（仅客户端）：Spring Boot 4 使用 Jackson 3，其 Maven 坐标有所变化（从 com.fasterxml.jackson.core 改为 tools.jackson.core）、采用不可变构建器（使用 JsonMapper.builder().build() 代替 new ObjectMapper()），并使用非受检异常（使用 JacksonException 代替 JsonProcessingException）。

Gradle 构建变更：Spring Boot 4 移除了 io.spring.dependency-management 插件。现在通过 Gradle 原生的 platform() BOM 管理依赖。Spring AI 2.0.0 已在 Maven Central 正式发布，因此无需配置里程碑版本仓库。

功能

MCP 服务

• 自然语言系统诊断：提出“是什么占用了我的 CPU？”等问题，即可获得智能解答
• 11 种专用工具，适用于常见诊断场景：
  • 执行自定义 Osquery SQL 查询
  • 获取表结构和可用列
  • 查找 CPU、内存或磁盘 I/O 使用率高的进程
  • 分析网络连接
  • 检查系统温度和风扇转速（macOS）
  • 识别可疑进程
  • 获取全面的系统健康状况摘要（并行执行）
  • 获取常见问题的示例查询
• 智能查询辅助：内置示例和结构发现功能可帮助 AI 构建更好的查询
• 基于 STDIO 的 MCP 集成：可与 Claude Desktop 及其他兼容 MCP 的 AI 工具无缝协作
• 使用 Java 25 的 Spring Boot 4.0.3：采用支持 GraalVM 原生镜像的最新 Spring 生态系统
• GraalVM 原生镜像：启动时间低于 200ms，可即时响应 MCP 请求（实测约 36ms）

Spring AI MCP 客户端

• Spring AI 自动配置：利用 Spring AI 2.0 的 MCP 客户端 starter，实现零配置设置
• 交互式 CLI：用于探索性系统诊断的 REPL 界面
• 自然语言处理：将用户问题映射到相应的服务工具
• 自定义 SQL 支持：通过 MCP 服务直接执行 osquery 命令
• 自动发现工具：通过注入 SyncMcpToolCallbackProvider 发现工具
• 内置错误处理：由框架管理超时和进程
• 声明式配置：基于 YAML 的设置，便于维护
• Jackson 3：使用不可变 JsonMapper 构建器模式和现代 API
• 全面测试：包含用于查询映射逻辑的自动化单元测试

Claude Code 技能

• 零开销：无需服务进程——直接通过 Bash 运行 osqueryi
• 自然语言触发：针对系统诊断问题自动激活
• 预定义查询模板：与 MCP 服务使用相同的诊断查询
• 基线指导：包含用于解读结果的“这正常吗？”背景信息
• 安全说明：解释哪些因素会使进程可疑（以及常见的误报）
• 平台意识：指出 macOS 与 Linux 的差异
• 易于维护：只需编辑 Markdown 文件并重启 Claude Code

性能与可靠性

• 原生镜像启动：约 36ms 即可收到首个 MCP 响应（而 JVM 启动需要数秒）
• 并行查询：系统运行状况摘要通过虚拟线程并发运行 5 个查询
• 查询超时：查询超时设为 30 秒，版本检查超时设为 5 秒，防止进程挂起
• 进程管理：使用 ProcessBuilder 实现可靠的资源处理和适当的清理
• 执行时间日志：跟踪查询性能，以便监控和调试
• 错误处理：捕获并返回查询失败时的详细错误消息
• 资源安全：自动终止超过超时限制的进程

前提条件

• Java 25+（推荐使用 GraalVM CE 25，以支持原生镜像）
  • 通过 SDKMAN 安装：sdk install java 25.0.2-graalce
• 已安装 Osquery，且 osqueryi 位于 PATH 中
• Gradle（或使用随附的 Gradle wrapper）

安装

1. 克隆仓库：

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

2. 构建项目：

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

3. 构建原生镜像（可选，推荐）：

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

4. 运行服务：

# JVM mode
./gradlew bootRun

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

5. 测试 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

6. 运行测试：

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

使用方法

MCP 服务

该服务以 STDIO 模式运行，并提供 11 个专用工具用于系统诊断：

Spring AI MCP 客户端

客户端提供多种与服务交互的方式：

自然语言查询

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

自定义 SQL 查询

../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

Claude Code 技能

在 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?

安装

选项 1：项目级（已包含在此仓库中）

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

选项 2：个人级（适用于所有项目）

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

工作原理

该技能会引导 Claude 直接运行 osqueryi 命令：

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

无需服务——Claude 通过 Bash 执行查询并解读 JSON 结果。

可用的服务工具

核心工具

• executeOsquery(sql)：执行任意有效的 Osquery SQL 查询
• listOsqueryTables()：获取系统上所有可用的 Osquery 表
• getTableSchema(tableName)：发现任意表的列和类型

诊断工具

• getHighCpuProcesses()：查找 CPU 占用最高的进程
• getHighMemoryProcesses()：查找内存占用最高的进程
• getHighDiskIOProcesses()：查找磁盘读写活动频繁的进程
• getNetworkConnections()：显示活动网络连接及进程信息
• getTemperatureInfo()：获取系统温度和风扇转速（macOS）
• getSuspiciousProcesses()：识别特征异常的进程

辅助工具

• getCommonQueries()：获取常见诊断场景的示例查询
• getSystemHealthSummary()：全面概览 CPU、内存、磁盘、网络和温度状况（通过虚拟线程并行运行所有查询）

AI 交互示例

无需编写复杂的 SQL，现在可以直接用自然语言提问：

“我的电脑为什么运行缓慢？” -> AI 使用 getHighCpuProcesses() 和 getHighMemoryProcesses()

“哪些程序正在连接互联网？” -> AI 使用 getNetworkConnections()

“为什么我的风扇这么吵？” -> AI 使用 getTemperatureInfo() 检查系统温度

“显示所有 Chrome 进程” -> AI 使用 executeOsquery() 并发现架构

“全面检查一下系统运行状况” -> AI 使用 getSystemHealthSummary() 进行全面诊断（并行运行 5 个查询）

“我的系统是否已被入侵？” -> AI 使用 getSuspiciousProcesses() 检查异常

配置

应用通过 src/main/resources/application.properties 进行配置：

• 服务名称：osquery-server
• 版本：1.0.0
• 模式：SYNC（同步操作）
• 传输方式：STDIO（标准输入/输出）

MCP 集成

此服务使用 Spring AI 的 MCP Server starter 实现 Model Context Protocol（MCP）。它可以集成到支持 MCP 的 AI 工具中，例如：

• Claude Desktop App
• 其他兼容 MCP 的 AI 助手

MCP 配置示例

对于 Claude Desktop，请将以下内容添加到配置中：

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

或者使用原生二进制文件，实现即时启动（约 36ms）：

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

安全注意事项

警告：此服务会以运行用户的权限执行系统命令。请考虑采取以下安全措施：

• 以满足需求的最低权限运行
• 在生产环境中实施查询过滤或白名单
• 监控并记录所有执行的查询
• 考虑使用只读的 Osquery 查询

开发

项目架构

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)

构建配置

项目使用 Gradle 和 platform() BOM 管理依赖（Spring Boot 4 移除了 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"))
    // ...
}

运行测试

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

构建原生镜像

# 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

注意：由于 GraalVM buildtools 插件 0.10.6 与 Gradle 9 的配置缓存序列化存在已知的不兼容问题，因此必须使用 --no-configuration-cache 标志。

内置诊断查询

此服务包含针对常见诊断场景的预构建查询。使用 getCommonQueries() 查看所有可用示例：

性能分析

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

网络分析

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

系统信息

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

AI 可以将这些查询用作模板，也可以直接调用专用诊断工具。

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT License。详情请参阅 许可证。

致谢

• Facebook 开发的 Osquery
• 用于实现 MCP 协议的 Spring AI MCP
• Spring Boot 框架
• 用于原生镜像编译的 GraalVM