Skip to main content
Glama
4R9UN

MCP KQL Server

by 4R9UN
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

MCP KQL Server

mcp-name: io.github.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.

MCP Registry PyPI version Python

CI/CD Pipeline codecov Security Rating Code Quality

FastMCP Azure Data Explorer MCP Protocol Maintenance MCP Badge

šŸŽ¬ Demo

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

MCP KQL Server Demo

šŸš€ 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.

    • Live Schema Validation: Ensures query accuracy by using live schema discovery.

  • schema_memory:

    • Schema Discovery: Discover and cache schemas for tables.

    • Database Exploration: List all tables within a database.

    • AI Context: Get AI-driven context for tables.

    • 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 kql_schema_memory functionality is now seamlessly integrated into the kql_execute tool. When you run a query, the server automatically discovers and caches the schema for any tables it hasn't seen before. This on-demand process ensures you always have the context you need without any manual steps.

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

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": { "mcp-kql-server": { "command": "python", "args": ["-m", "mcp_kql_server"], "env": {} } } }

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

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

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": { "command": "python", "args": [ "-m", "mcp_kql_server" ], "type": "stdio", "alwaysAllow": [ ] }, }

Generic MCP Client

For any MCP-compatible application:

# Command to run the server python -m mcp_kql_server # Server provides these tools: # - kql_execute: Execute KQL queries with AI context # - kql_schema_memory: Discover and cache 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

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

3. Use via MCP Client

The server provides two main tools:

kql_execute - Execute KQL Queries with AI Context

kql_schema_memory - Discover and Cache 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 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/>Device Code<br/>CLI Auth"] end %% Client to Server Client ==>|"šŸ“” MCP Protocol<br/>STDIO/SSE"| 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

Report Generated by MCP-KQL-Server | ā­ Star this repo on GitHub

šŸš€ Production Deployment

Ready to deploy MCP KQL Server to Azure for production use? We provide comprehensive deployment automation for Azure Container Apps with enterprise-grade security and scalability.

šŸŒŸ Features

  • āœ… Serverless Compute: Azure Container Apps with auto-scaling

  • āœ… Managed Identity: Passwordless authentication with Azure AD

  • āœ… Infrastructure as Code: Bicep templates for reproducible deployments

  • āœ… Monitoring: Integrated Log Analytics and Application Insights

  • āœ… Secure by Default: Network isolation, RBAC, and least-privilege access

  • āœ… One-Command Deploy: Automated PowerShell and Bash scripts

šŸ“– Deployment Guide

For complete deployment instructions, architecture details, and troubleshooting:

šŸ‘‰

The guide includes:

  • šŸ—ļø Detailed architecture diagrams

  • āš™ļø Step-by-step deployment instructions (PowerShell & Bash)

  • šŸ”’ Security configuration best practices

  • šŸ› Troubleshooting common issues

  • šŸ“¦ Docker containerization details

Quick Deploy

# 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"

šŸ“ Project Structure

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

šŸ”’ Security

  • Azure CLI Authentication: Leverages your existing Azure device login

  • No Credential Storage: Server doesn't store authentication tokens

  • Local Memory: Schema cache stored locally, not transmitted

šŸ› Troubleshooting

Common Issues

  1. Authentication Errors

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

  2. Memory Issues

    # 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. Connection Timeouts

    • Check cluster URI format

    • Verify network connectivity

    • Confirm Azure permissions

šŸ¤ Contributing

We welcome contributions! Please do.

šŸ“ž Support

šŸŒŸ Star History

Star History Chart

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

Happy Querying! šŸŽ‰

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/4R9UN/mcp-kql-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server