Skip to main content
Glama

MCP KQL Server

by 4R9UN
GitHub
Python
23
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP KQL Server

MseeP.ai Security Assessment Badge

AI-Powered KQL Query Execution with Intelligent Schema Memory

A Model Context Protocol (MCP) server that provides intelligent KQL (Kusto Query Language) query execution with AI-powered schema caching and context assistance for Azure Data Explorer clusters.

Verified on MseeP 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

graph TD A[MCP Client<br/>Claude/AI/Custom] <--> B[MCP KQL Server<br/>FastMCP Framework] B <--> C[Azure Data Explorer<br/>Kusto Clusters] B <--> D[Schema Memory<br/>Local AI Cache] style A fill:#4a90e2,stroke:#2c5282,stroke-width:3px,color:#ffffff style B fill:#8e44ad,stroke:#6a1b99,stroke-width:3px,color:#ffffff style C fill:#e67e22,stroke:#bf6516,stroke-width:3px,color:#ffffff style D fill:#27ae60,stroke:#1e8449,stroke-width:3px,color:#ffffff

šŸ“ 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

Happy Querying! šŸŽ‰

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables intelligent KQL query execution against Azure Data Explorer clusters with AI-powered schema caching and natural language to KQL conversion. Provides automated schema discovery and context-aware query assistance for enhanced data exploration.

  1. šŸŽ¬ Demo
    1. šŸš€ Features
      1. šŸ“Š MCP Tools Execution Flow
        1. Schema Memory Discovery Flow
      2. šŸ“‹ Prerequisites
        1. šŸš€ One-Command Installation
          1. Quick Install (Recommended)
          2. Alternative Installation Methods
        2. šŸ“± MCP Client Configuration
          1. Claude Desktop
          2. VSCode (with MCP Extension)
          3. Roo-code Or Cline (VS-code Extentions)
          4. Generic MCP Client
        3. šŸ”§ Quick Start
          1. 1. Authenticate with Azure (One-time setup)
          2. 2. Start the MCP Server (Zero configuration)
          3. 3. Use via MCP Client
        4. šŸ’” Usage Examples
          1. Basic Query Execution
          2. Complex Analytics Query
          3. Schema Discovery
          4. Data Exploration with Context
          5. Time-based Analysis
        5. šŸŽÆ Key Benefits
          1. For Data Analysts
          2. For DevOps Teams
          3. For AI Applications
        6. šŸ—ļø Architecture
          1. šŸ“ Project Structure
            1. šŸ”’ Security
              1. šŸ› Troubleshooting
                1. Common Issues
              2. šŸ¤ Contributing
                1. šŸ“ž Support
                  1. šŸŒŸ Star History

                    New MCP Servers

                    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