Mcp Kql Server

MCP KQL Server

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

[](https://mseep.ai/app/4r9un-mcp-kql-server)

> AI-Powered KQL Query Execution with Natural Language to KQL (NL2KQL) Conversion and Execution

A Model Context Protocol (MCP) server that transforms natural language questions into optimized KQL queries with intelligent schema discovery, AI-powered caching, and seamless Azure Data Explorer integration. Simply ask questions in plain English and get instant, accurate KQL queries with context-aware results.

Latest Version: v2.1.4 - Canonical schema type normalization for sharper NL2KQL accuracy, credential redaction in logs, leaner dependencies, and a single-source package version.

[](https://mseep.ai/app/18772353-3d90-4b12-a253-cf752efaadd2) [](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.4R9UN/mcp-kql-server) [](https://pypi.org/project/mcp-kql-server/) [](https://pypi.org/project/mcp-kql-server/)

[](https://github.com/4R9UN/mcp-kql-server/actions) [](https://codecov.io/gh/4R9UN/mcp-kql-server) [](https://github.com/4R9UN/mcp-kql-server/security) [](https://github.com/4R9UN/mcp-kql-server)

[](https://github.com/jlowin/fastmcp) [](https://azure.microsoft.com/en-us/services/data-explorer/) [](https://github.com/anthropics/mcp) [](https://github.com/4R9UN/mcp-kql-server/graphs/commit-activity) [](https://lobehub.com/mcp/4r9un-mcp-kql-server)

🎬 Demo

Watch a quick demo of the MCP KQL Server in action:

[](https://www.youtube.com/watch?v=Ca-yuThJ3Vc)

🚀 Features

• execute_kql_query:
• Natural Language to KQL: Generate KQL queries from natural language descriptions.
• Direct KQL Execution: Execute raw KQL queries.
• Multiple Output Formats: Supports JSON, CSV, and table formats.
• Strict Schema Validation: Uses discovered schema memory and validation before execution.
• Schema-Grounded Repair: Repairs invalid columns only when a valid table schema can prove the replacement.

• kql_schema_memory:
• Schema Discovery: Discover and cache schemas for tables.
• Database Exploration: List all tables within a database.
• AI Context: Get ranked CAG context for tables, with optional table-scoped strict schema output.
• Analysis Reports: Generate reports with visualizations.
• Cache Management: Clear or refresh the schema cache.
• Memory Statistics: Get statistics about the memory usage.

📊 MCP Tools Execution Flow

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

Schema Memory Discovery Flow

The schema memory flow is integrated into query execution, but it now reuses existing cached schema before attempting live discovery. If a table schema is already available in CAG/schema memory, the server will use that cached schema instead of re-indexing it.

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

📋 Prerequisites

• Python 3.10 or higher
• Azure CLI installed and authenticated (az login)
• Access to Azure Data Explorer cluster(s)

🚀 One-Command Installation

Quick Install (Recommended)

From Source

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

Alternative Installation Methods

pip install mcp-kql-server

That's it! The server automatically:

• ✅ Sets up memory directories in %APPDATA%\KQL_MCP (Windows) or ~/.local/share/KQL_MCP (Linux/Mac)
• ✅ Configures optimal defaults for production use
• ✅ Suppresses verbose Azure SDK logs
• ✅ No environment variables required

📱 MCP Client Configuration

> One-time install (any platform): > ``bash > pip install --upgrade mcp-kql-server > ` > After install, configure your MCP client to launch the server via the Python module entry point: python -m mcpkqlserver. This works on every platform where Python is on PATH and does not depend on the location of the mcp-kql-server console script. (The console script is still installed by pip` and remains supported for backward compatibility — see the alternative snippets below.)

Claude Desktop

Add to your Claude Desktop MCP settings file (mcp_settings.json):

Location:

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

Alternatives: platform-stable launchers or the installed console script

Windows (the py launcher is commonly available as py; use Get-Command py if you need its full path):

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

On macOS / Linux replace "py" with "python3" and drop the "-3" arg.

VSCode (with MCP Extension)

Add to your VSCode MCP configuration:

Settings.json location:

• 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": "false",
        "MCP_KQL_CHECK_FOR_UPDATES": "false",
        "MCP_KQL_DEFER_AUTH": "1",
        "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"
      }
    }
  }
}

> If VS Code logs spawn ...PythonNNN/python.exe ENOENT, the Python extension is substituting a cached interpreter path for "python". Switch to "py" (Windows) / "python3" (macOS/Linux), or to the "mcp-kql-server" console script that pip install drops on PATH. See [docs/troubleshooting.md](docs/troubleshooting.md#8-mcp-integration-issues) for full details.

> Windows tip: use py -3 -m mcp_kql_server so VS Code does not need a user-specific Python path. If you must use a full path locally, keep it in your private mcp.json, not in shared documentation.

> If the server starts but VS Code still shows no tools, run MCP: Reset Cached Tools, then MCP: Reset Trust, and restart the server from MCP: List Servers. VS Code stores trust and cached tools separately from mcp.json, so a previous failed launch can keep the old empty state until you reset it.

Shared HTTP Mode for Multiple MCP Clients

Use shared HTTP when VS Code, GitHub Copilot CLI, agents, or other MCP clients should connect to one persistent MCP KQL server process.

Start the server:

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

Client configuration:

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

Runtime Settings Added in v2.1.3

| Option or environment variable | Purpose | Default | | --- | --- | --- | | --transport, FASTMCP_TRANSPORT | stdio, http, streamable-http, or sse | stdio | | --host, FASTMCP_HOST | HTTP bind host | 127.0.0.1 | | --port, FASTMCP_PORT | HTTP bind port | 8000 | | --http-path, FASTMCP_STREAMABLE_HTTP_PATH | Streamable HTTP endpoint path | /mcp | | --stateless-http, FASTMCP_STATELESS_HTTP | Stateless HTTP mode for shared deployments | false | | --auth-on-startup, MCP_KQL_AUTH_ON_STARTUP | Check Azure CLI auth before startup | false | | --check-updates, MCP_KQL_CHECK_FOR_UPDATES | Check PyPI for package updates before startup | false | | MCP_KQL_AUTH_CHECK_TIMEOUT_SECONDS | Azure CLI auth check timeout | 10 | | MCP_KQL_AUTH_LOGIN_TIMEOUT_SECONDS | Interactive Azure login timeout | 120 | | MCP_KQL_SQLITE_BUSY_TIMEOUT_MS | SQLite busy timeout for concurrent local MCP instances | 30000 |

Roo-code Or Cline (VS-code Extentions)

Ask or Add to your Roo-code Or Cline MCP settings:

MCP Settings location:

• All platforms: Through Roo-code extension settings or mcp_settings.json

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

Generic MCP Client

For any MCP-compatible application:

# 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

🔧 Quick Start

1. Authenticate with Azure (One-time setup)

az login

2. Start the MCP Server (Zero configuration)

python -m mcp_kql_server

To inspect the installed server version and runtime defaults:

python -m mcp_kql_server --info --json

The server starts immediately with:

• 📁 Auto-created memory path: %APPDATA%\KQL_MCP\cluster_memory
• 🔧 Optimized defaults: No configuration files needed
• 🔐 Secure setup: Uses your existing Azure CLI credentials
• ⚡ Fast startup: Auth and update checks are deferred unless explicitly enabled

3. Use via MCP Client

The server provides two main tools:

> #### execute_kql_query - Execute KQL queries or generate KQL from natural language > #### kql_schema_memory - Discover, refresh, and inspect cached cluster schemas

💡 Usage Examples

Basic Query Execution

Ask your MCP client (like Claude): > "Execute this KQL query against the help cluster: cluster('help.kusto.windows.net').database('Samples').StormEvents | take 10 and summarize the result and give me high level insights "

Complex Analytics Query

Ask your MCP client: > "Query the Samples database in the help cluster to show me the top 10 states by storm event count, include visualization"

Schema Discovery

Ask your MCP client: > "Discover and cache the schema for the help.kusto.windows.net cluster, then tell me what databases and tables are available"

Data Exploration with Context

Ask your MCP client: > "Using the StormEvents table in the Samples database on help cluster, show me all tornado events from 2007 with damage estimates over $1M"

Time-based Analysis

Ask your MCP client: > "Analyze storm events by month for the year 2007 in the StormEvents table, group by event type and show as a visualization"

🎯 Key Benefits

For Data Analysts

• ⚡ Faster Query Development: AI-powered autocomplete and suggestions
• 🎨 Rich Visualizations: Instant markdown tables for data exploration
• 🧠 Context Awareness: Understand your data structure without documentation

For DevOps Teams

• 🔄 Automated Schema Discovery: Keep schema information up-to-date
• 💾 Smart Caching: Reduce API calls and improve performance
• 🔐 Secure Authentication: Leverage existing Azure CLI credentials

For AI Applications

• 🤖 Intelligent Query Assistance: AI-generated table descriptions and suggestions
• 📊 Structured Data Access: Clean, typed responses for downstream processing
• 🎯 Context-Aware Responses: Rich metadata for better AI decision making

🏗️ Architecture

%%{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 ClientClaude / AI / Custom─────────Natural LanguageInterface"]
    
    subgraph Server["🚀 MCP KQL Server"]
        direction TB
        FastMCP["⚡ FastMCPFramework─────────MCP ProtocolHandler"]
        NL2KQL["🧠 NL2KQLEngine─────────AI QueryGeneration"]
        Executor["⚙️ QueryExecutor─────────Validation &Execution"]
        Memory["💾 SchemaMemory─────────AI Cache"]
        
        FastMCP --> NL2KQL
        NL2KQL --> Executor
        Executor --> Memory
        Memory --> Executor
    end
    
    subgraph Azure["☁️ Azure Services"]
        direction TB
        ADX["📊 Azure DataExplorer─────────Kusto

…

## Source & license

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

- **Author:** [4R9UN](https://github.com/4R9UN)
- **Source:** [4R9UN/mcp-kql-server](https://github.com/4R9UN/mcp-kql-server)
- **License:** MIT

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