Osquery MCP Server

Osquery MCP サーバー、クライアント、スキル

Osquery を AI アシスタントと統合するための完全な実装です。Claude Desktop 向けの MCP サーバー、Spring AI クライアント、CLI を直接利用する Claude Code スキルの 3 つの方法を提供します。

概要

このプロジェクトでは、自然言語を Osquery SQL クエリに変換することで、「ファンがこんなに熱く回っているのはなぜ？」や「メモリをすべて使っているのは何？」といったシステム診断の質問に AI アシスタントが回答できるようになります。

AI で osquery を利用する 3 つの方法：

アプローチ	最適な用途	仕組み
MCP サーバー	Claude Desktop	Spring Boot サーバーが MCP プロトコルで通信します
Spring AI クライアント	プログラムからのアクセス	Spring AI の MCP 自動構成を使用する CLI クライアント
Claude Code スキル	Claude Code CLI	Bash 経由で osqueryi を直接実行するため、サーバーは不要です

新機能

GraalVM ネイティブイメージのサポートとともに、スタックを最新の Spring エコシステムにアップグレードしました。

コンポーネント	以前	現在
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 plugin	Gradle platform() BOM
ネイティブイメージ	非対応	GraalVM ネイティブバイナリ（起動時間約36ms）
システムヘルス	順次実行（5つのクエリ）	仮想スレッドによる並列実行

主なアップグレードの詳細

GraalVM ネイティブイメージ：MCP サーバーは約62MBのネイティブバイナリにコンパイルされ、約36msで起動して MCP リクエストに応答します。これは音声インターフェースのユースケースで重要です。JavaFX 音声クライアントがサーバーを起動する際、即座に応答する必要があるためです。

仮想スレッド：getSystemHealthSummary() は Executors.newVirtualThreadPerTaskExecutor() と CompletableFuture.supplyAsync() を使用して、5つの診断クエリ（CPU、メモリ、ディスク、ネットワーク、温度）をすべて並列実行するようになりました。これにより、応答時間をすべてのクエリの合計時間から、最も時間のかかる単一クエリの所要時間まで短縮します。

Jackson 3 への移行（クライアントのみ）：Spring Boot 4 には、新しい Maven 座標（com.fasterxml.jackson.core ではなく tools.jackson.core）、不変ビルダー（new ObjectMapper() ではなく JsonMapper.builder().build()）、チェック例外ではない例外（JsonProcessingException ではなく JacksonException）を備えた Jackson 3 が同梱されています。

Gradle ビルドの変更：Spring Boot 4 では io.spring.dependency-management plugin が廃止されました。依存関係は Gradle 標準の platform() BOM で管理するようになりました。Spring AI 2.0.0 は Maven Central で GA となったため、マイルストーンリポジトリは不要です。

機能

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 ネイティブイメージ：即時の MCP 応答を実現する、200ms 未満の起動時間（実測値約36ms）

Spring AI MCP クライアント

• Spring AI の自動設定：Spring AI 2.0 の MCP クライアントスターターを活用し、設定不要でセットアップできます
• 対話型 CLI：システム診断を調べるための REPL インターフェースを提供します
• 自然言語処理：ユーザーの質問を適切なサーバーツールに対応付けます
• カスタム SQL のサポート：MCP サーバーを介して osquery コマンドを直接実行します
• ツールの自動検出：SyncMcpToolCallbackProvider のインジェクションを通じてツールを検出します
• 組み込みのエラー処理：フレームワークがタイムアウトとプロセス管理を処理します
• 宣言的な設定：メンテナンスが容易な YAML ベースのセットアップです
• Jackson 3：不変の JsonMapper ビルダーパターンと最新の API を使用します
• 包括的なテスト：クエリのマッピングロジックを対象とする自動ユニットテストが含まれています

Claude Code スキル

• オーバーヘッドなし：サーバープロセスは不要です。Bash 経由で osqueryi を直接実行します
• 自然言語トリガー：システム診断に関する質問に自動的に反応します
• 事前定義済みクエリテンプレート：MCP サーバーと同じ診断クエリを使用します
• 基準情報の提示：結果を解釈するための「これは正常ですか？」というコンテキストを含みます
• セキュリティに関する説明：プロセスが不審と判断される理由（およびよくある誤検知）を説明します
• プラットフォームへの配慮：macOS と Linux の違いについて説明します
• メンテナンスが容易：Markdown ファイルのみで構成されており、編集して Claude Code を再起動するだけです

パフォーマンスと信頼性

• ネイティブイメージの起動：最初の MCP 応答まで約 36 ミリ秒（JVM の起動には数秒かかります）
• 並列クエリ：システムの健全性サマリーでは、仮想スレッドを使って 5 つのクエリを並行実行します
• クエリのタイムアウト：クエリには 30 秒、バージョン確認には 5 秒のタイムアウトを設定し、処理が停止するのを防ぎます
• プロセス管理：ProcessBuilder を使用してリソースを堅牢に管理し、適切にクリーンアップします
• 実行時間のログ記録：監視とデバッグのためにクエリのパフォーマンスを記録します
• エラー処理：失敗したクエリから詳細なエラーメッセージを取得して返します
• リソースの安全性：タイムアウト制限を超えたプロセスを自動的に終了します

前提条件

• Java 25 以降（ネイティブイメージのサポートには GraalVM CE 25 を推奨）
  • SDKMAN でインストール：sdk install java 25.0.2-graalce
• Osquery がインストールされており、osqueryi が PATH から利用できること
• Gradle（または同梱の Gradle ラッパーを使用）

インストール

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"]
    }
  }
}

または、ネイティブバイナリを使えば、すぐに起動できます（約 36 ミリ秒）。

{
  "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 はこれらをテンプレートとして使用することも、専用の診断ツールを直接呼び出すこともできます。

貢献

貢献を歓迎します。お気軽にプルリクエストを送信してください。

ライセンス

MIT License。詳細は ライセンス を参照してください。

謝辞

• Facebook による Osquery
• MCP プロトコルの実装に使用した Spring AI MCP
• Spring Boot フレームワーク
• ネイティブイメージのコンパイルに使用した GraalVM