KQL MCP

KQL MCP Server

The best MCP server for KQL (Kusto Query Language) — supporting Azure Data Explorer, Log Analytics, and Microsoft Sentinel.

Features

Tools

| Tool | Description | |------|-------------| | execute_query | Execute KQL against ADX or Log Analytics | | list_connections | List configured connections | | list_databases | List databases in an ADX cluster | | list_tables | List tables in a database or workspace | | get_table_schema | Get column names, types, and descriptions | | get_sample_data | Get sample rows to understand a table | | search_schema | Find tables/columns by keyword | | get_table_stats | Row count and storage size (ADX) | | validate_query | Validate KQL syntax and get optimization tips | | get_query_templates | Browse battle-tested query templates | | search_templates | Search templates by keyword | | kql_reference_search | Look up any KQL operator or function | | clear_schema_cache | Refresh cached schema data |

Resources (KQL Reference)

• Tabular operators: where, summarize, join, project, extend, parse, mv-expand, make-series, etc.
• Scalar functions: string, datetime, math, dynamic/JSON, IP address
• Aggregation functions: count, dcount, avg, percentile, make_list, arg_max, etc.
• Window functions: prev, next, row_number, row_cumsum
• Time series functions: series_decompose_anomalies, series_fit_line, series_decompose_forecast
• Data types and timespan literals
• Best practices for performance, readability, and security

Query Templates

• Security: Failed logins, impossible travel, suspicious PowerShell, Azure resource deletions, network anomalies
• Performance: CPU/memory/disk metrics, slow HTTP requests, dependency failures, exception rates
• Operations: Heartbeat health checks, VM events, ingestion volume, alert rule firings
• ADX: Query statistics, ingestion failures, extent stats
• Time Series: Anomaly detection, forecasting, event rate spikes

Prompts

• write-kql — Write a KQL query from a natural language description
• explain-kql — Explain what a query does in plain English
• optimize-kql — Analyze and optimize a query for performance
• investigate-security-alert — Security investigation plan + queries
• performance-investigation — Performance root cause queries
• convert-sql-to-kql — Convert SQL to KQL
• schema-explorer — Explore a table and get query suggestions

Installation

pip install git+https://github.com/rod-trent/KQL-MCP.git

Or clone and install locally:

git clone https://github.com/rod-trent/KQL-MCP.git
cd KQL-MCP
pip install -e .

Configuration

Copy .env.example to .env and fill in your connection details:

# Azure Data Explorer
ADX_CLUSTERS='[{"name": "my-cluster", "cluster_url": "https://mycluster.eastus.kusto.windows.net", "database": "mydb"}]'

# Log Analytics / Sentinel
LOG_ANALYTICS_WORKSPACES='[{"name": "sentinel", "workspace_id": "your-workspace-id"}]'

# Authentication (cli = az login, managed_identity, service_principal, interactive)
AZURE_AUTH_METHOD=cli

Authentication

The server supports multiple Azure authentication methods:

| Method | Use case | |--------|----------| | cli | Local development — uses az login | | managed_identity | Azure-hosted workloads (VMs, Container Apps, etc.) | | service_principal | CI/CD pipelines, automated workflows | | interactive | Browser-based interactive login |

For cli auth, log in first:

az login

---

Using with AI Assistants

The KQL MCP server works with any AI assistant or IDE that supports the Model Context Protocol (MCP). Choose your platform below.

---

Claude Desktop

Config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kql": {
      "command": "kql-mcp",
      "env": {
        "ADX_CLUSTERS": "[{\"name\": \"my-cluster\", \"cluster_url\": \"https://mycluster.eastus.kusto.windows.net\", \"database\": \"mydb\"}]",
        "LOG_ANALYTICS_WORKSPACES": "[{\"name\": \"sentinel\", \"workspace_id\": \"your-workspace-id\"}]",
        "AZURE_AUTH_METHOD": "cli"
      }
    }
  }
}

Alternatively, point to a directory containing your .env file:

{
  "mcpServers": {
    "kql": {
      "command": "kql-mcp",
      "cwd": "C:\\path\\to\\KQL-MCP"
    }
  }
}

Restart Claude Desktop after saving. You should see the KQL tools available in a new conversation.

---

Claude Code (CLI)

claude mcp add kql -- kql-mcp

To pass connection config directly:

claude mcp add kql \
  -e ADX_CLUSTERS='[{"name":"prod","cluster_url":"https://mycluster.eastus.kusto.windows.net","database":"mydb"}]' \
  -e AZURE_AUTH_METHOD=cli \
  -- kql-mcp

Verify the server is registered:

claude mcp list

---

ChatGPT (OpenAI)

OpenAI supports MCP servers in the ChatGPT desktop app (macOS and Windows).

Config file location:

• Windows: %APPDATA%\ChatGPT\claude_desktop_config.json
• macOS: ~/Library/Application Support/ChatGPT/claude_desktop_config.json

{
  "mcpServers": {
    "kql": {
      "command": "kql-mcp",
      "env": {
        "ADX_CLUSTERS": "[{\"name\": \"my-cluster\", \"cluster_url\": \"https://mycluster.eastus.kusto.windows.net\", \"database\": \"mydb\"}]",
        "LOG_ANALYTICS_WORKSPACES": "[{\"name\": \"sentinel\", \"workspace_id\": \"your-workspace-id\"}]",
        "AZURE_AUTH_METHOD": "cli"
      }
    }
  }
}

Restart ChatGPT after saving. MCP tools appear automatically when you start a new conversation.

> Note: MCP support in ChatGPT desktop requires the latest version of the app. Check OpenAI's documentation for the most current setup instructions.

---

Cursor

Open Settings → Cursor Settings → MCP and add a new server, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "kql": {
      "command": "kql-mcp",
      "env": {
        "ADX_CLUSTERS": "[{\"name\": \"my-cluster\", \"cluster_url\": \"https://mycluster.eastus.kusto.windows.net\", \"database\": \"mydb\"}]",
        "LOG_ANALYTICS_WORKSPACES": "[{\"name\": \"sentinel\", \"workspace_id\": \"your-workspace-id\"}]",
        "AZURE_AUTH_METHOD": "cli"
      }
    }
  }
}

Reload Cursor after saving. The KQL tools will be available to Cursor's AI in Agent mode.

---

Windsurf (Codeium)

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kql": {
      "command": "kql-mcp",
      "env": {
        "ADX_CLUSTERS": "[{\"name\": \"my-cluster\", \"cluster_url\": \"https://mycluster.eastus.kusto.windows.net\", \"database\": \"mydb\"}]",
        "LOG_ANALYTICS_WORKSPACES": "[{\"name\": \"sentinel\", \"workspace_id\": \"your-workspace-id\"}]",
        "AZURE_AUTH_METHOD": "cli"
      }
    }
  }
}

Restart Windsurf after saving. MCP tools are available in Cascade (Windsurf's AI agent).

---

VS Code (GitHub Copilot)

Add to your VS Code settings.json (open via Ctrl+Shift+P → Preferences: Open User Settings (JSON)):

{
  "mcp": {
    "servers": {
      "kql": {
        "type": "stdio",
        "command": "kql-mcp",
        "env": {
          "ADX_CLUSTERS": "[{\"name\": \"my-cluster\", \"cluster_url\": \"https://mycluster.eastus.kusto.windows.net\", \"database\": \"mydb\"}]",
          "LOG_ANALYTICS_WORKSPACES": "[{\"name\": \"sentinel\", \"workspace_id\": \"your-workspace-id\"}]",
          "AZURE_AUTH_METHOD": "cli"
        }
      }
    }
  }
}

Or add a workspace-scoped .vscode/mcp.json file to share the config with your team:

{
  "servers": {
    "kql": {
      "type": "stdio",
      "command": "kql-mcp",
      "env": {
        "ADX_CLUSTERS": "[{\"name\": \"my-cluster\", \"cluster_url\": \"https://mycluster.eastus.kusto.windows.net\", \"database\": \"mydb\"}]",
        "AZURE_AUTH_METHOD": "cli"
      }
    }
  }
}

The KQL tools are then available in GitHub Copilot Chat when using Agent mode (@agent).

---

Any Other MCP-Compatible Client

The server speaks standard MCP over stdio. Any client that supports stdio MCP servers can use it with this generic config shape:

{
  "mcpServers": {
    "kql": {
      "command": "kql-mcp",
      "env": {
        "ADX_CLUSTERS": "[{\"name\": \"\", \"cluster_url\": \"https://..kusto.windows.net\", \"database\": \"\"}]",
        "LOG_ANALYTICS_WORKSPACES": "[{\"name\": \"\", \"workspace_id\": \"\"}]",
        "AZURE_AUTH_METHOD": "cli"
      }
    }
  }
}

Key values:

| Key | Description | |-----|-------------| | command | kql-mcp (the installed CLI entry point) | | ADX_CLUSTERS | JSON array of ADX cluster connections | | LOG_ANALYTICS_WORKSPACES | JSON array of Log Analytics workspace connections | | AZURE_AUTH_METHOD | cli, managed_identity, service_principal, or interactive |

Refer to your AI client's MCP documentation for the exact config file location and format.

---

Requirements

• Python 3.11+
• Azure CLI (az login) for cli auth mode, or appropriate credentials for other auth methods
• Access to an Azure Data Explorer cluster or Log Analytics / Sentinel workspace

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rod-trent
• Source: rod-trent/KQL-MCP
• License: MIT

Install and usage instructions live in the source repository linked above.