🚀 MCP KQL Server

MCP KQL サーバー

mcp-name: io.github.4R9UN/mcp-kql-server

AI を活用した KQL クエリの実行。自然言語から KQL への変換（NL2KQL）と実行に対応

自然言語の質問を、インテリジェントなスキーマ検出、AI を活用したキャッシュ、Azure Data Explorer とのシームレスな統合により、最適化された KQL クエリに変換する Model Context Protocol（MCP）サーバーです。平易な英語で質問するだけで、コンテキストを考慮した正確な結果と KQL クエリをすぐに取得できます。

最新バージョン：v2.1.5 - ポリシーに準拠した Azure CLI ログインと、公式 MCP Python SDK への移行。

🎬 デモ

MCP KQL Server の動作を短いデモでご覧ください：

🚀 機能

• execute_kql_query：

  • 自然言語から KQL へ：自然言語の説明から KQL クエリを生成します。
  • KQL の直接実行：生の KQL クエリを実行します。
  • 複数の出力形式：JSON、CSV、テーブル形式に対応しています。
  • 厳密なスキーマ検証：検出済みのスキーマメモリを使用し、実行前に検証します。
  • スキーマに基づく修正：有効なテーブルスキーマで置き換えを確認できる場合に限り、無効な列を修正します。

• kql_schema_memory：

  • スキーマ検出：テーブルのスキーマを検出してキャッシュします。
  • データベースの探索：データベース内のすべてのテーブルを一覧表示します。
  • AI コンテキスト：テーブルの優先順位付けされた CAG コンテキストを取得します。オプションで、テーブルに限定した厳密なスキーマ出力にも対応しています。
  • 分析レポート：可視化を含むレポートを生成します。
  • キャッシュ管理：スキーマキャッシュを消去または更新します。
  • メモリ統計：メモリ使用量の統計を取得します。

📊 MCP ツールの実行フロー

graph TD
    A[👤 User Submits KQL Query] --> B{🔍 Query Validation}
    B -->|❌ Invalid| C[📝 Syntax Error Response]
    B -->|✅ Valid| D[🧠 Load Schema Context]

    D --> E{💾 Schema Cache Available?}
    E -->|✅ Yes| F[⚡ Load from Memory]
    E -->|❌ No| G[🔍 Discover Schema]

    F --> H[🎯 Execute Query]
    G --> I[💾 Cache Schema + AI Context]
    I --> H

    H --> J{🎯 Query Success?}
    J -->|❌ Error| K[🚨 Enhanced Error Message]
    J -->|✅ Success| L[📊 Process Results]

    L --> M[🎨 Generate Visualization]
    M --> N[📤 Return Results + Context]

    K --> O[💡 AI Suggestions]
    O --> N

    style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff
    style B fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style C fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff
    style D fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style F fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
    style G fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style H fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
    style I fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style J fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style K fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff
    style L fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
    style M fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style N fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
    style O fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff

スキーマメモリの検出フロー

スキーマメモリのフローはクエリ実行に統合されていますが、ライブ検出を試みる前に、既存のキャッシュ済みスキーマを再利用するようになりました。テーブルスキーマがすでに CAG／スキーマメモリにある場合、サーバーは再インデックスせずに、そのキャッシュ済みスキーマを使用します。

graph TD
    A[👤 User Requests Schema Discovery] --> B[🔗 Connect to Cluster]
    B --> C[📂 Enumerate Databases]
    C --> D[📋 Discover Tables]

    D --> E[🔍 Get Table Schemas]
    E --> F[🤖 AI Analysis]
    F --> G[📝 Generate Descriptions]

    G --> H[💾 Store in Memory]
    H --> I[📊 Update Statistics]
    I --> J[✅ Return Summary]

    style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff
    style B fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style C fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style D fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
    style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style F fill:#e67e22,stroke:#bf6516,stroke-width:2px,color:#ffffff
    style G fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style H fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style I fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
    style J fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff

📋 前提条件

• Python 3.10 以上
• Azure CLI がインストールされていること。サーバーの起動時に現在のトークンを確認し、必要な場合に限り、通常の対話型 az login を実行します。
• Azure Data Explorer クラスターへのアクセス権

🚀 1 コマンドでインストール

クイックインストール（推奨）

ソースから

git clone https://github.com/4R9UN/mcp-kql-server.git && cd mcp-kql-server && pip install -e .

その他のインストール方法

pip install mcp-kql-server

これで完了です！ サーバーは自動的に以下を実行します。

• ✅ %APPDATA%\KQL_MCP（Windows）または ~/.local/share/KQL_MCP（Linux/Mac）にメモリ用ディレクトリを設定します
• ✅ 本番環境での使用に最適なデフォルト設定を構成します
• ✅ 詳細な Azure SDK ログを抑制します
• ✅ 環境変数は必要ありません

📱 MCP クライアントの設定

すべてのプラットフォームでの初回インストール：

pip install --upgrade mcp-kql-server

インストール後、Python モジュールのエントリーポイント python -m mcp_kql_server を使ってサーバーを起動するように MCP クライアントを設定します。これは Python が PATH にあるすべてのプラットフォームで動作し、mcp-kql-server コンソールスクリプトの場所に依存しません。（コンソールスクリプトは引き続き pip によってインストールされ、後方互換性のためサポートされています。以下の代替スニペットを参照してください。）

Claude Desktop

Claude Desktop の MCP 設定ファイル（mcp_settings.json）に追加します。

場所：

• Windows：%APPDATA%\Claude\mcp_settings.json
• macOS：~/Library/Application Support/Claude/mcp_settings.json
• Linux：~/.config/Claude/mcp_settings.json

{
  "mcpServers": {
    "mcpKqlServer": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mcp_kql_server"]
    }
  }
}

{
  "mcpServers": {
    "mcpKqlServer": {
      "type": "stdio",
      "command": "py",
      "args": ["-3", "-m", "mcp_kql_server"]
    }
  }
}

VSCode（MCP Extension を使用）

VSCode の MCP 設定に追加します。

Settings.json の場所：

• Windows：%APPDATA%\Code\User\mcp.json
• macOS：~/Library/Application Support/Code/User/mcp.json
• Linux：~/.config/Code/User/mcp.json

{
  "servers": {
    "mcpKqlServer": {
      "type": "stdio",
      "command": "py",
      "args": ["-3", "-m", "mcp_kql_server", "--transport", "stdio"],
      "timeout": 300000,
      "env": {
        "FASTMCP_TRANSPORT": "stdio",
        "MCP_KQL_AUTH_ON_STARTUP": "true",
        "MCP_KQL_CHECK_FOR_UPDATES": "false",
        "MCP_KQL_SKIP_STARTUP_VERSION_CHECK": "1",
        "MCP_KQL_AUTH_CHECK_TIMEOUT_SECONDS": "10",
        "MCP_KQL_AUTH_LOGIN_TIMEOUT_SECONDS": "120",
        "MCP_KQL_SQLITE_BUSY_TIMEOUT_MS": "30000"
      }
    }
  }
}

VS Code に spawn ...PythonNNN/python.exe ENOENT と記録される場合、Python 拡張機能が "python" の代わりにキャッシュ済みのインタープリターのパスを使用しています。"py"（Windows）／"python3"（macOS/Linux）に切り替えるか、pip install によって PATH に追加される "mcp-kql-server" コンソールスクリプトを使用してください。詳しくは docs/troubleshooting.md を参照してください。

Windows のヒント：py -3 -m mcp_kql_server を使用すれば、VS Code でユーザー固有の Python パスを指定する必要はありません。ローカルでフルパスを使用する必要がある場合は、共有ドキュメントではなく、個人用の mcp.json に記載してください。

サーバーが起動しても VS Code にツールが表示されない場合は、MCP: Reset Cached Tools を実行し、続いて MCP: Reset Trust を実行してから、MCP: List Servers でサーバーを再起動してください。VS Code では信頼状態とキャッシュ済みツールが mcp.json とは別に保存されるため、起動に一度失敗すると、リセットするまで古い空の状態が保持されることがあります。

複数の MCP クライアント向け共有 HTTP モード

VS Code、GitHub Copilot CLI、エージェント、その他の MCP クライアントから、1 つの永続的な MCP KQL サーバープロセスに接続する場合は、共有 HTTP を使用します。

ツール呼び出しはオペレーターの Azure CLI ID で実行されるため、HTTP のバインド先はデフォルトでループバックに制限されています。外部に公開する前に、信頼できるリバースプロキシで認証と TLS を設定してください。ループバック以外へのバインドには、明示的な確認として MCP_KQL_ALLOW_UNAUTHENTICATED_REMOTE_HTTP=true が必要です。

サーバーを起動します。

python -m mcp_kql_server --transport http --host 127.0.0.1 --port 8000 --http-path /mcp --stateless-http

クライアントの設定：

{
  "servers": {
    "mcpKqlServer": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

ランタイム設定

埋め込みモデルは必要になったときに読み込まれます。モデルを変更すると、更新時にスキーマが再度埋め込まれます。また、他のモデルで生成されたベクトルは混在させず、無視されます。

Roo-code または Cline（VS-code 拡張機能）

Roo-code または Cline の MCP 設定で、以下を追加または設定してください。

MCP 設定の場所：

• すべてのプラットフォーム：Roo-code 拡張機能の設定、または mcp_settings.json から

{
  "mcp-kql-server": {
    "type": "stdio",
    "command": "python",
    "args": ["-m", "mcp_kql_server"],
    "alwaysAllow": []
  }
}

汎用 MCP クライアント

MCP 互換アプリケーションで使用する場合：

# Preferred: invoke as a Python module (cross-platform)
python -m mcp_kql_server

# Platform-stable launchers (recommended if `python` is ambiguous on PATH)
py -3 -m mcp_kql_server     # Windows
python3 -m mcp_kql_server   # macOS / Linux

# Equivalent console script installed by pip
mcp-kql-server

# Shared HTTP mode for multiple clients
python -m mcp_kql_server --transport http --host 127.0.0.1 --port 8000 --http-path /mcp --stateless-http

# Server provides these tools:
# - execute_kql_query: Execute KQL or generate KQL from natural language
# - kql_schema_memory: Discover, cache, and inspect cluster schemas

🔧 クイックスタート

1. MCP サーバーを起動する（設定不要）

python -m mcp_kql_server

サーバーの起動時に、Azure CLI のトークンチェックがバックグラウンドで開始され、必要な場合にのみ通常の対話型 az login が実行されます。Kusto ツールの呼び出し時にログインが開始されることはありません。実行前に起動時のタスクが完了するまで待機します。サーバーを起動する前に手動で認証するには、次を実行します。

az login

インストール済みサーバーのバージョンとランタイムのデフォルト設定を確認するには：

python -m mcp_kql_server --info --json

サーバーは次の設定で直ちに起動します：

• 📁 メモリパスを自動作成：%APPDATA%\KQL_MCP\cluster_memory
• 🔧 最適化されたデフォルト設定：設定ファイルは不要です
• 🔐 安全なセットアップ：既存の Azure CLI 資格情報を使用します
• ⚡ 応答性の高い起動：認証をバックグラウンドで初期化しながら、MCP の検出を直ちに開始します

3. MCP クライアントから使用する

サーバーは主に 2 つのツールを提供します：

execute_kql_query - KQL クエリを実行するか、自然言語から KQL を生成します

kql_schema_memory - キャッシュされたクラスターのスキーマを検出、更新、確認します

💡 使用例

基本的なクエリの実行

MCP クライアント（Claude など）に次のように依頼します：

"次の KQL クエリを help クラスターに対して実行してください：cluster('help.kusto.windows.net').database('Samples').StormEvents | take 10。結果を要約し、概要を説明してください。"

複雑な分析クエリ

MCP クライアントに次のように依頼します：

"help クラスターの Samples データベースをクエリして、暴風雨イベント数が多い上位 10 州を表示し、可視化してください。"

スキーマの検出

MCP クライアントに次のように依頼します。

「help.kusto.windows.net クラスターのスキーマを検出してキャッシュし、利用可能なデータベースとテーブルを教えてください」

コンテキストを踏まえたデータ探索

MCP クライアントに次のように依頼します。

「help クラスターの Samples データベースにある StormEvents テーブルを使用して、2007 年に発生した竜巻のうち、被害額の推定が 100 万ドルを超えるものをすべて表示してください」

時系列分析

MCP クライアントに次のように依頼します。

「StormEvents テーブルの 2007 年の暴風雨イベントを月別に分析し、イベントの種類ごとにグループ化して、可視化して表示してください」

🎯 主なメリット

データアナリスト向け

• ⚡ クエリ開発の高速化：AI を活用した自動補完と提案
• 🎨 豊富な可視化：データ探索に使える Markdown テーブルをすぐに表示
• 🧠 コンテキスト認識：ドキュメントがなくてもデータ構造を把握

DevOps チーム向け

• 🔄 スキーマの自動検出：スキーマ情報を最新の状態に維持
• 💾 スマートキャッシュ：API 呼び出しを減らし、パフォーマンスを向上
• 🔐 セキュアな認証：既存の Azure CLI 資格情報を活用

AI アプリケーション向け

• 🤖 インテリジェントなクエリ支援：AI が生成するテーブルの説明と提案
• 📊 構造化データへのアクセス：後続処理に適した、整然とした型付きレスポンス
• 🎯 コンテキストを考慮したレスポンス：AI のより適切な意思決定を支える豊富なメタデータ

🏗️ アーキテクチャ

%%{init: {'theme':'dark', 'themeVariables': {
  'primaryColor':'#1a1a2e',
  'primaryTextColor':'#00d9ff',
  'primaryBorderColor':'#00d9ff',
  'secondaryColor':'#16213e',
  'secondaryTextColor':'#c77dff',
  'secondaryBorderColor':'#c77dff',
  'tertiaryColor':'#0f3460',
  'tertiaryTextColor':'#ffaa00',
  'tertiaryBorderColor':'#ffaa00',
  'lineColor':'#00d9ff',
  'textColor':'#ffffff',
  'mainBkg':'#0a0e27',
  'nodeBorder':'#00d9ff',
  'clusterBkg':'#16213e',
  'clusterBorder':'#9d4edd',
  'titleColor':'#00ffff',
  'edgeLabelBackground':'#1a1a2e',
  'fontFamily':'Inter, Segoe UI, sans-serif',
  'fontSize':'16px',
  'flowchart':{'nodeSpacing':60, 'rankSpacing':80, 'curve':'basis', 'padding':20}
}}}%%
graph LR
    Client["🖥️ MCP Client<br/><b>Claude / AI / Custom</b><br/>─────────<br/>Natural Language<br/>Interface"]

    subgraph Server["🚀 MCP KQL Server"]
        direction TB
        FastMCP["⚡ FastMCP<br/>Framework<br/>─────────<br/>MCP Protocol<br/>Handler"]
        NL2KQL["🧠 NL2KQL<br/>Engine<br/>─────────<br/>AI Query<br/>Generation"]
        Executor["⚙️ Query<br/>Executor<br/>─────────<br/>Validation &<br/>Execution"]
        Memory["💾 Schema<br/>Memory<br/>─────────<br/>AI Cache"]

        FastMCP --> NL2KQL
        NL2KQL --> Executor
        Executor --> Memory
        Memory --> Executor
    end

    subgraph Azure["☁️ Azure Services"]
        direction TB
        ADX["📊 Azure Data<br/>Explorer<br/>─────────<br/><b>Kusto Cluster</b><br/>KQL Engine"]
        Auth["🔐 Azure<br/>Identity<br/>─────────<br/>Interactive<br/>CLI Auth"]
    end

    %% Client to Server
    Client ==>|"📡 MCP Protocol<br/>stdio or streamable HTTP"| FastMCP

    %% Server to Azure
    Executor ==>|"🔍 Execute KQL<br/>Query & Analyze"| ADX
    Executor -->|"🔐 Authenticate"| Auth
    Memory -.->|"📥 Fetch Schema<br/>On Demand"| ADX

    %% Styling - Using cyberpunk palette
    style Client fill:#1a1a2e,stroke:#00d9ff,stroke-width:4px,color:#00ffff
    style FastMCP fill:#16213e,stroke:#c77dff,stroke-width:3px,color:#c77dff
    style NL2KQL fill:#1a1a40,stroke:#ffaa00,stroke-width:3px,color:#ffaa00
    style Executor fill:#16213e,stroke:#9d4edd,stroke-width:3px,color:#9d4edd
    style Memory fill:#0f3460,stroke:#00d9ff,stroke-width:3px,color:#00d9ff
    style ADX fill:#1a1a2e,stroke:#ff6600,stroke-width:4px,color:#ff6600
    style Auth fill:#16213e,stroke:#00ffff,stroke-width:2px,color:#00ffff

    style Server fill:#0a0e27,stroke:#9d4edd,stroke-width:3px,stroke-dasharray: 5 5
    style Azure fill:#0a0e27,stroke:#ff6600,stroke-width:3px,stroke-dasharray: 5 5

MCP-KQL-Server が生成したレポート | ⭐ GitHub でこのリポジトリにスターを付ける

🚀 本番環境へのデプロイ

MCP KQL Server を Azure にデプロイして本番環境で利用する準備はできていますか？エンタープライズレベルのセキュリティとスケーラビリティを備えた Azure Container Apps 向けに、包括的なデプロイ自動化を提供しています。

🌟 機能

• ✅ サーバーレスコンピューティング：自動スケーリングに対応した Azure Container Apps
• ✅ マネージド ID：Azure AD によるパスワードレス認証
• ✅ Infrastructure as Code：再現可能なデプロイを実現する Bicep テンプレート
• ✅ モニタリング：Log Analytics と Application Insights を統合
• ✅ デフォルトでセキュア：ネットワーク分離、RBAC、最小権限アクセス
• ✅ 1 コマンドでデプロイ：PowerShell および Bash の自動化スクリプト

📖 デプロイガイド

デプロイ手順、アーキテクチャの詳細、トラブルシューティングについては、次をご覧ください。

👉 本番環境へのデプロイガイドを見る

ガイドには次の内容が含まれています。

• 🏗️ 詳細なアーキテクチャ図
• ⚙️ 手順に沿ったデプロイ方法（PowerShell および Bash）
• 🔒 セキュリティ設定のベストプラクティス
• 🐛 よくある問題のトラブルシューティング
• 📦 Docker によるコンテナー化の詳細

クイックデプロイ

# PowerShell (Windows)
cd deployment
.\deploy.ps1 -SubscriptionId "YOUR_SUB_ID" -ResourceGroupName "mcp-kql-prod-rg" -ClusterUrl "https://yourcluster.region.kusto.windows.net"

# Bash (Linux/Mac/WSL)
cd deployment
./deploy.sh --subscription "YOUR_SUB_ID" --resource-group "mcp-kql-prod-rg" --cluster-url "https://yourcluster.region.kusto.windows.net"

📁 プロジェクト構成

mcp-kql-server/
├── mcp_kql_server/
│   ├── __init__.py          # Package initialization
│   ├── mcp_server.py        # Main MCP server implementation
│   ├── execute_kql.py       # KQL query execution logic
│   ├── memory.py            # Advanced memory management
│   ├── kql_auth.py          # Azure authentication
│   ├── utils.py             # Utility functions
│   └── constants.py         # Configuration constants
├── docs/                    # Documentation
├── Example/                 # Usage examples
├── pyproject.toml          # Project configuration
└── README.md               # This file

🔒 セキュリティ

• Azure CLI 認証：既存のトークンを再利用するか、ブラウザーでの対話型ログインを開始します
• 資格情報を保存しない：サーバーは認証トークンを保存しません
• ローカルメモリ：スキーマキャッシュはローカルに保存され、外部に送信されません

🐛 トラブルシューティング

よくある問題

1. 認証エラー

   # Re-authenticate with Azure CLI
   az login --tenant your-tenant-id
   

2. メモリの問題

   # The memory cache is now managed automatically. If you suspect issues,
   # you can clear the cache directory, and it will be rebuilt on the next query.
   # Windows:
   rmdir /s /q "%APPDATA%\KQL_MCP\unified_memory.json"
   
   # macOS/Linux:
   rm -rf ~/.local/share/KQL_MCP/cluster_memory
   

3. 接続タイムアウト

   • クラスター URI の形式を確認してください
   • ネットワーク接続を確認してください
   • Azure のアクセス許可を確認してください

🤝 コントリビューション

コントリビューションを歓迎します！ぜひご参加ください。

📞 サポート

• 問題の報告：GitHub Issues
• PyPI パッケージ：PyPI プロジェクトページ
• 作者：Arjun Trivedi
• 認定：MCPHub

🌟 スター履歴

mcp-name: io.github.4R9UN/mcp-kql-server

クエリをお楽しみください！🎉