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\": \"<alias>\", \"cluster_url\": \"https://<cluster>.<region>.kusto.windows.net\", \"database\": \"<database>\"}]",
        "LOG_ANALYTICS_WORKSPACES": "[{\"name\": \"<alias>\", \"workspace_id\": \"<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