Azure Kusto MCP Server

Azure Kusto MCP サーバー

Azure Kusto に接続し、AI アシスタントがデータスキーマを探索して KQL クエリを実行できるようにする、Model Context Protocol（MCP）サーバーです。

特長

• Azure Kusto との連携：Azure Kusto クラスターに安全に接続します
• スキーマの探索：AI アシスタント向けのリソースとしてテーブルスキーマを公開します
• クエリの実行：KQL クエリの実行と結果の分析に使用するツールを提供します
• データ分析の支援：一般的なデータ分析タスク向けの組み込みプロンプトを提供します
• VS Code との連携：VS Code 内で対話形式で接続情報を設定します

必要条件

• Python 3.9+
• Azure Kusto クラスターへのアクセス
• GitHub Copilot または Copilot Chat 拡張機能がインストールされた VS Code（MCP のサポートに必要）
• 必要な Python パッケージ（セットアップスクリプトで自動的にインストールされます）

クイックセットアップ（推奨）

VS Code との連携を含め、MCP サーバーを最も簡単にセットアップする方法です。

python setup-mcp.py

このスクリプトでは、次の処理が行われます。

1. 必要な依存関係をすべてインストールします
2. VS Code との連携に必要な設定を作成します
3. サーバーの起動方法を案内します

手動インストール

1. リポジトリをクローンします。

git clone https://github.com/yourusername/kusto-mcp-server.git
cd kusto-mcp-server

2. 必要な依存関係をインストールします。

pip install -r requirements.txt

3. （任意）環境変数を設定します。 ルートディレクトリに .env ファイルを作成し、次の変数を設定します。

AZURE_KUSTO_CLUSTER=https://<your-cluster>.kusto.windows.net
AZURE_KUSTO_DATABASE=<your-database>

mcp.json 設定ファイルの作成

VS Code で MCP サーバーを設定するには、mcp.json ファイルが必要です。手動でセットアップする場合、またはセットアップスクリプトでこのファイルが作成されなかった場合は、次の手順に従ってください。

1. ワークスペースの .vscode ディレクトリに mcp.json という名前の新しいファイルを作成します（このディレクトリがない場合は作成してください）。
2. 次の内容をファイルに追加します。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "kusto-cluster",
      "description": "Azure Kusto Cluster URL (e.g., https://mycluster.kusto.windows.net)",
      "default": ""
    },
    {
      "type": "promptString",
      "id": "kusto-database",
      "description": "Azure Kusto Database Name",
      "default": ""
    }
  ],
  "servers": {
    "Azure Kusto MCP": {
      "type": "stdio",
      "command": "${command:python.interpreterPath}",
      "args": ["${workspaceFolder}/src/kusto_mcp/server.py"],
      "env": {
        "AZURE_KUSTO_CLUSTER": "${input:kusto-cluster}",
        "AZURE_KUSTO_DATABASE": "${input:kusto-database}",
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}

3. 必要に応じて設定をカスタマイズします。
   • 特定の Python インタープリターのパスを使う必要がある場合は、command を変更します
   • サーバースクリプトが別の場所にある場合は、args を変更します
   • 必要に応じて環境変数を追加します
   • ${workspaceFolder} と ${command:python.interpreterPath} は VS Code の変数であり、適切なパスに自動的に置き換えられます

この設定には入力プロンプトが含まれており、サーバーを起動するたびに Kusto クラスターの URL とデータベース名を尋ねます。これにより、異なるデータベースを簡単に切り替えられます。

VS Code との連携

VS Code で MCP サーバーを使用するには、次の手順に従ってください。

1. セットアップスクリプトを実行したことを確認します。python setup-mcp.py を実行するか、手動で mcp.json ファイルを作成してください
2. VS Code に GitHub Copilot または Copilot Chat 拡張機能をインストールします
3. コマンドパレットを開きます（Ctrl+Shift+P）
4. 「MCP: Start Server with Configuration」を実行します
5. リストから「Azure Kusto MCP」を選択します
6. プロンプトが表示されたら、Kusto クラスターの URL とデータベース名を入力します

MCP サーバーが起動し、Copilot Chat セッションに接続されます。次の操作が可能になります。

• connect ツールを使用して Kusto クラスターに接続する
• テーブルスキーマを参照する
• クエリを実行する
• データを分析する

VS Code を使わずにサーバーを実行する

次のコマンドで MCP サーバーを直接起動します。

python -m src.kusto_mcp.server

.env ファイルで接続を設定していない場合は、必要に応じてサーバーが接続情報を尋ねます。

認証

このサーバーは認証に Azure の DefaultAzureCredential を使用します。次の方法がサポートされています。

1. 環境変数
2. マネージド ID
3. Azure CLI の資格情報
4. Azure PowerShell の資格情報
5. フォールバックとしての対話型ブラウザー認証

接続する前に、これらの方法のうち少なくとも 1 つで認証されていることを確認してください。

リソースの種類

サーバーは次のリソースを公開します。

• kusto/tables - 現在のデータベースにあるすべてのテーブルの一覧
• kusto/schema/{table_name} - 特定のテーブルのスキーマ
• kusto/sample - KQL クエリのサンプルと説明
• kusto/connection - 現在の接続情報

ツール

以下のツールを利用できます。

• connect - Kusto クラスターとデータベースに接続します
• connection_status - 現在の接続状態を確認します
• execute_query - KQL クエリを実行します
• analyze_data - クエリを実行し、結果を分析します
• optimize_query - クエリの最適化に関する提案を取得します

ツールの使用ガイド

Kusto MCP サーバーは、Azure Kusto を操作するための複数のツールを提供します。各ツールの効果的な使い方は次のとおりです。

Connect ツール

connect ツールは、Azure Kusto クラスターとデータベースへの接続を確立します。

Copilot Chat での使用方法：

I need to connect to my Kusto cluster

このツールでは、次の情報を求められます。

• クラスターの URL（例：https://yourcluster.kusto.windows.net）
• データベース名

認証は Azure の DefaultAzureCredential によって自動的に処理されます。

例：

Connect to the Kusto database named "MyDatabase" on the cluster "analytics.kusto.windows.net"

Connection Status ツール

connection_status ツールは、現在の接続の詳細を表示します。

Copilot Chat での使用方法：

Check my current Kusto connection

出力例：

✅ Connected to Azure Kusto.
        
- **Cluster**: https://analytics.kusto.windows.net
- **Database**: MyDatabase

Execute Query ツール

execute_query ツールは、接続中のデータベースに対して KQL クエリを実行します。

Copilot Chat での使用方法：

Run this KQL query: <your query here>

例：

Run this KQL query: StormEvents | where State == "FLORIDA" | take 10

結果が 100 行を超える場合、ツールは概要と最初の 10 行を返します。

Analyze Data ツール

analyze_data ツールは、クエリを実行し、その結果を分析します。

Copilot Chat での使用方法：

Analyze this query: <your query here>

分析の種類を指定できます。

• summary（デフォルト）：データの基本統計
• stats：相関関係を含む詳細な統計分析
• plot_ready：データを視覚化するための情報

例：

Analyze this query with stats analysis: StormEvents | summarize count() by State | top 10 by count_

Optimize Query ツール

optimize_query ツールは、KQL クエリを改善するための提案を提供します。

Copilot Chat での使用方法：

Optimize this KQL query: <your query here>

例：

Optimize this KQL query: 
StormEvents
| project *
| where StartTime > ago(7d)
| sort by StartTime desc

高度な使用シナリオ

テーブルスキーマの確認

利用可能なテーブルとそのスキーマを確認するには：

What tables are available in this database?

特定のテーブルのスキーマを調べるには：

Show me the schema for the StormEvents table

時系列分析

時間ベースのデータを分析するには：

Help me analyze time trends in the StormEvents table using the StartTime column

相関分析

列間の関係を調べるには：

Find correlations between DamageProperty and DeathsDirect in the StormEvents table

データ品質チェック

データ品質を確認するには：

Check for null values and outliers in the StormEvents table

段階的なクエリの作成

複雑なクエリについて、手順を尋ねることができます。

I need to build a query that shows storm events by state, with damage amounts, limited to the top 10 most expensive events. Can you help me construct this?

ベストプラクティス

1. 必ず最初に接続する：クエリを実行する前に、connect ツールを使用します
2. 接続を確認する：接続状態が不明な場合は、connection_status ツールを使用します
3. 小さなクエリから始める：大規模なデータセットに対して実行する前に、take または limit 演算子を使ってクエリをテストします
4. 分析ツールを使う：analyze_data ツールを使うと、最小限の手間で有用な分析結果を得られます
5. 最適化を依頼する：実行に時間のかかるクエリや複雑なクエリには、optimize_query ツールを使用します

KQL クエリの例

まずは次の KQL クエリの例をお試しください。

// Simple filtering
StormEvents 
| where State == "FLORIDA" 
| take 10

// Aggregation
StormEvents
| summarize EventCount=count() by State
| order by EventCount desc
| take 10

// Time filtering
StormEvents
| where StartTime > ago(30d)
| summarize EventCount=count() by bin(StartTime, 1d)
| render timechart

// Join example
StormEvents
| where EventType == "Tornado"
| join (
    StormEvents 
    | where EventType == "Flood"
    | project State, FloodTime=StartTime
) on State
| project State, TornadoTime=StartTime, FloodTime
| take 10

MCP 設定のトラブルシューティング

MCP の設定で問題が発生した場合：

1. mcp.json がない：上記の説明に従って、.vscode ディレクトリにファイルを手動で作成します
2. 設定が表示されない：mcp.json ファイルの形式が正しく、.vscode ディレクトリに配置されていることを確認します
3. サーバーに接続できない：mcp.json ファイルで指定したホスト名とポートが利用可能であることを確認します
4. Copilot がサーバーを検出しない：mcp.json ファイルの作成後または変更後に、VS Code を再起動します

よくある問題のトラブルシューティング

前述の一般的なトラブルシューティングのヒントに加えて、ツールでよく発生する問題への具体的な解決方法を以下に示します。

Connect ツールの問題

• エラー：「Failed to connect」：Azure の資格情報が有効であり、指定したクラスターとデータベースへのアクセス権があることを確認します
• タイムアウトエラー：ネットワーク接続とファイアウォールの設定を確認します
• 認証エラー：az login で Azure にログインしているか、有効な環境資格情報が設定されていることを確認します

クエリ実行に関する問題

• 大規模なクエリのタイムアウト：フィルターや時間制約を追加して、データ量を減らしてください
• 構文エラー：optimize_query ツールを使用して、クエリの構文を確認し、修正してください
• 列が見つからない：クエリを実行する前に、スキーマを調べて列名を確認してください

データ分析に関する問題

• 分析結果が空：分析する前に、クエリがデータを返すことを確認してください
• 相関分析のエラー：相関分析には、データに少なくとも2つの数値列が含まれていることを確認してください
• 可視化の準備：plot_ready 分析で最良の結果を得るには、カテゴリ列と数値列の両方を含めてください

AI アシスタントでの使用

この MCP サーバーは、Model Context Protocol に対応する AI アシスタントと連携するように設計されています。サーバーは Azure Kusto データへの構造化されたアクセスを提供し、AI アシスタントは次のことを行えます。

1. 利用可能なテーブルとスキーマを確認する
2. 読み取り専用の KQL クエリを実行する
3. クエリ結果を分析する
4. データ分析に関するガイダンスを提供する

セキュリティに関する考慮事項

• サーバーは安全な認証に Azure の DefaultAzureCredential を使用します
• 適切な権限を持つユーザーのみが Kusto クラスターにアクセスできます
• 資格情報がサーバー自体に保存されることはありません

ライセンス

MIT ライセンス