Osquery MCP Server

Osquery MCP服务器、客户端和技能

集成的完整实施 Osquery 使用AI助手，提供三种方法：用于Claude Desktop的MCP服务器、Spring AI客户端和用于直接CLI使用的Claude Code技能。

概述

该项目通过将自然语言翻译成Osquery SQL查询，使人工智能助手能够回答系统诊断问题，如“为什么我的风扇运行得这么热？”或“什么在使用我所有的内存？”。

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

特性

MCP服务器

• 自然语言系统诊断问诸如“我的CPU在用什么？”之类的问题，并得到明智的答案
• 9专用工具 对于常见的诊断场景：

- 执行自定义Osquery SQL查询 - 获取表架构和可用列 - 查找CPU/内存使用率高的进程 - 分析网络连接 - 检查系统温度和风扇速度（macOS） - 获取全面的系统运行状况摘要 - 访问常见问题的示例查询

• 智能查询辅助：内置示例和模式发现有助于AI构建更好的查询
• 基于STDIO的MCP集成：与Claude Desktop和其他MCP兼容的AI工具无缝协作
• 使用Java 21的Spring Boot 3.5：使用Java 17+功能的现代、高效和可维护的代码库

Spring AI MCP客户端

• Spring AI自动配置：利用Spring AI的MCP客户端启动器进行零配置设置
• 交互式CLI：探索性系统诊断的REPL接口
• 自然语言处理：将人工问题映射到适当的服务器工具
• 自定义SQL支持：通过MCP服务器执行直接osquery命令
• 自动工具发现：通过以下方式发现的工具 SyncMcpToolCallbackProvider 注射
• 内置错误处理：框架管理的超时和流程管理
• 声明性配置：基于YAML的设置，便于维护
• 综合测试：包括查询映射逻辑的自动单元测试

克劳德代码技能

• 零开销：不需要服务器进程-运行 osqueryi 直接通过Bash
• 自然语言触发器：系统诊断问题自动激活
• 预定义查询模板：与MCP服务器相同的诊断查询
• 基线指导：包括用于解释结果的“这正常吗？”上下文
• 安全说明：解释流程可疑的原因（以及常见的误报）
• 平台意识：注意macOS与Linux的差异
• 易于维护：只需标记文件-编辑并重新启动Claude Code

性能和可靠性

• 查询超时：防止查询超时30秒，版本检查超时5秒挂起
• 流程管理：使用ProcessBuilder进行稳健的资源处理和适当的清理
• 执行时间记录：跟踪查询性能以进行监视和调试
• 错误处理：从失败的查询中捕获并返回详细的错误消息
• 资源安全：自动销毁超过超时限制的进程

先决条件

• Java 21或更高版本
• Osquery 安装和 osqueryi 在您的PATH中可用
• Gradle（或使用附带的Gradle包装）

安装

1. 克隆存储库：

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

1. 构建项目：

./gradlew build        # Build server
./gradlew bootJar      # Create executable JAR
cd client-springai && ../gradlew build  # Build Spring AI client

1. 运行服务器：

./gradlew bootRun

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

1. 运行测试：

./gradlew test --tests OsqueryServiceTest    # Server tests
cd client-springai && ../gradlew test       # Spring AI client tests

用法

MCP服务器

服务器在STDIO模式下运行，并提供九种用于系统诊断的专用工具：

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

自定义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中询问系统诊断问题时，该技能会自动激活：

> 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

运作原理

这项技能引导克劳德奔跑 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()：查找使用最多内存的进程
• getNetworkConnections()：显示带有进程信息的活动网络连接
• getTemperatureInfo()：获取系统温度和风扇速度（macOS）

辅助工具

• getCommonQueries()：获取常见诊断场景的示例查询
• getSystemHealthSummary()：全面了解CPU、内存、磁盘、网络和温度

AI交互示例

现在，您可以问自然语言问题，而不是编写复杂的SQL：

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

“什么连接到互联网？” → AI使用 getNetworkConnections()

“为什么我的粉丝这么大声？” → AI使用 getTemperatureInfo() 检查系统温度

“显示所有Chrome进程” → AI使用 executeOsquery() 使用模式发现

“给我做一次全面的系统健康检查” → AI使用 getSystemHealthSummary() 用于全面诊断

配置

应用程序通过以下方式配置 src/main/resources/application.properties:

• 服务器名称：osquery服务器
• 版本: 1.0.0
• 模式：SYNC（同步操作）
• 运输：STDIO（标准输入/输出）

MCP集成

该服务器使用Spring AI的MCP服务器启动器实现模型上下文协议（MCP）。它可以与支持MCP的AI工具集成，例如：

• Claude桌面应用程序
• 其他与MCP兼容的AI助手

MCP配置示例

对于Claude Desktop，请添加到您的配置中：

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

安全考虑

⚠️ 警告：此服务器以运行用户的权限执行系统命令。考虑以下安全措施：

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

发展

项目结构

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

项目架构

├── src/                                    # MCP Server (Spring Boot)
│   ├── main/java/com/kousenit/osquerymcpserver/
│   │   ├── OsqueryMcpServerApplication.java      # Main application
│   │   └── OsqueryService.java                   # MCP tools
│   └── test/java/com/kousenit/osquerymcpserver/
│       └── OsqueryServiceTest.java               # Server tests
├── client-springai/                        # Spring AI MCP Client
│   ├── src/main/java/com/kousenit/osqueryclient/springai/
│   │   └── SpringAiOsqueryClientApplication.java # CLI application
│   ├── 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 config

运行测试

./gradlew test                           # Server tests
cd client-springai && ../gradlew test    # Spring AI client tests
./test-client-springai.sh                # Full client test suite

内置诊断查询

该服务器包括用于常见诊断场景的预构建查询。使用 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)

人工智能可以将这些作为模板或直接调用专门的诊断工具。

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证。看 许可证 了解详情。

致谢

• Osquery 通过Facebook
• 春季AI MCP 用于MCP协议实现
• Spring Boot框架