MCP KQL Server

by 4r9un

24 stars
328 downloads
Not rated
GitHub

About

Execute KQL queries using Azure authentication. Requires Azure CLI login.

Details

Author
4r9un
GitHub stars
24
Downloads
328
Categories
Database, Other, Search
Tags
#azure, #data-analysis

Jump to

- Natural Language to KQL (NL2KQL) conversion
- Execute raw KQL queries directly
- Schema discovery and AI-powered caching
- Support for JSON, CSV, and table output formats
- Schema-grounded repair of invalid query columns
- Cache management and memory statistics

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name MCP KQL Server
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

1. Start the MCP Server (Zero configuration)

Server startup begins an Azure CLI token check in the background and runs plain interactiveaz loginonly when needed. Kusto tool calls never launch login; they wait for that startup task before executing. To authenticate manually before starting the server, run:

To inspect the installed server version and runtime defaults:

- 📁Auto-created memory path:%APPDATA%\KQL_MCP\cluster_memory
- 🔧Optimized defaults: No configuration files needed
- 🔐Secure setup: Uses your existing Azure CLI credentials
- ⚡Responsive startup: MCP discovery starts immediately while authentication initializes in the background

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "mcp kql server": {
            "mcp-kql-server": {
                "command": "python",
                "args": [
                    "-m",
                    "mcp_kql_server",
                    "--transport",
                    "http",
                    "--host",
                    "127.0.0.1",
                    "--port",
                    "8000",
                    "--http-path",
                    "/mcp",
                    "--stateless-http"
                ]
            }
        }
    }
}

McpServers

{
    "mcp-kql-server": {
        "command": "python",
        "args": [
            "-m",
            "mcp_kql_server",
            "--transport",
            "http",
            "--host",
            "127.0.0.1",
            "--port",
            "8000",
            "--http-path",
            "/mcp",
            "--stateless-http"
        ]
    }
}

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.

Latest Version: v2.1.5- Policy compliant Azure CLI login and migration to the official MCP Python SDK.

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

- 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.

- 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.

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

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

- Python 3.10 or higher
- Azure CLIinstalled. Server startup checks the current token and runs plain interactiveaz loginonly when needed.
- Access to Azure Data Explorer cluster(s)

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

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

After install, configure your MCP client to launch the server via the Python module entry point:python -m mcp_kql_server. This works on every platform where Python is onPATHand does not depend on the location of themcp-kql-serverconsole script. (The console script is still installed bypipand remains supported for backward compatibility — see the alternative snippets below.)

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

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

Windows (thepylauncher is commonly available aspy; useGet-Command pyif 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.

- 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": "true", "MCP_KQL_CHECK_FOR_UPDATES": "false", "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 logsspawn ...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 thatpip installdrops onPATH. Seedocs/troubleshooting.mdfor full details.

Windows tip: usepy -3 -m mcp_kql_serverso VS Code does not need a user-specific Python path. If you must use a full path locally, keep it in your privatemcp.json, not in shared documentation.

If the server starts but VS Code still shows no tools, runMCP: Reset Cached Tools, thenMCP: Reset Trust, and restart the server fromMCP: List Servers. VS Code stores trust and cached tools separately frommcp.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.

HTTP binds are restricted to loopback by default because tool calls execute with the operator's Azure CLI identity. Put authentication and TLS in a trusted reverse proxy before remote exposure. Non-loopback binding requires the explicitMCP_KQL_ALLOW_UNAUTHENTICATED_REMOTE_HTTP=trueacknowledgement.

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

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

The embedding model is lazy loaded. Changing it causes schemas to be re-embedded on refresh, and vectors produced by other models are ignored rather than mixed.

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

- All platforms: Through Roo-code extension settings ormcp_settings.json

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

# 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

1. Start the MCP Server (Zero configuration)

Server startup begins an Azure CLI token check in the background and runs plain interactiveaz loginonly when needed. Kusto tool calls never launch login; they wait for that startup task before executing. To authenticate manually before starting the server, run:

To inspect the installed server version and runtime defaults:

- 📁Auto-created memory path:%APPDATA%\KQL_MCP\cluster_memory
- 🔧Optimized defaults: No configuration files needed
- 🔐Secure setup: Uses your existing Azure CLI credentials
- ⚡Responsive startup: MCP discovery starts immediately while authentication initializes in the background

execute_kql_query- Execute KQL queries or generate KQL from natural language

kql_schema_memory- Discover, refresh, and inspect cached cluster schemas

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

"Query the Samples database in the help cluster to show me the top 10 states by storm event count, include visualization"

"Discover and cache the schema for the help.kusto.windows.net cluster, then tell me what databases and tables are available"

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

"Analyze storm events by month for the year 2007 in the StormEvents table, group by event type and show as a visualization"

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

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

- 🤖 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

%%{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/>Interactive<br/>CLI Auth"] end %% Client to Server Client ==>|"📡 MCP Protocol<br/>stdio or streamable HTTP"| 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

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

- ✅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

For complete deployment instructions, architecture details, and troubleshooting:

- 🏗️ Detailed architecture diagrams
- ⚙️ Step-by-step deployment instructions (PowerShell & Bash)
- 🔒 Security configuration best practices
- 🐛 Troubleshooting common issues
- 📦 Docker containerization details

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

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

- Azure CLI Authentication: Reuses an existing token or starts interactive browser login
- No Credential Storage: Server doesn't store authentication tokens
- Local Memory: Schema cache stored locally, not transmitted

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

# 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

- Check cluster URI format
- Verify network connectivity
- Confirm Azure permissions

- Issues:GitHub Issues
- PyPI Package:PyPI Project Page
- Author:Arjun Trivedi
- Certified:MCPHub

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

An MCP server for integrating with Azure Data Explorer, allowing for data querying and management.

An MCP server for Azure Data Explorer (Kusto) that enables AI assistants to interact with Kusto databases.

An analytics server providing tools for interacting with the Microsoft Fabric data platform.

Integrate with Power BI using a local server for offline .pbix file analysis and an Azure server for querying live datasets.

A read-only MCP server for Azure Data Catalog, powered by CData's JDBC driver.

Official MCP server for dbt (data build tool) providing integration with dbt Core/Cloud CLI, project metadata discovery, model information, and semantic layer querying capabilities.

Provides AI assistants with a secure and structured way to explore and analyze data in GreptimeDB.

Build robust data workflows, integrations, and analytics on a single intuitive platform.

Query and analyze data with MotherDuck and local DuckDB

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "mcp kql server": {
            "mcp-kql-server": {
                "command": "python",
                "args": [
                    "-m",
                    "mcp_kql_server",
                    "--transport",
                    "http",
                    "--host",
                    "127.0.0.1",
                    "--port",
                    "8000",
                    "--http-path",
                    "/mcp",
                    "--stateless-http"
                ]
            }
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other