LABSCO SUMMARY

Natural-language KQL that is checked against the real schema before it runs.

The schema memory is what makes the generation worth trusting: tables are discovered once, cached with ranked context, and used to validate the query, so a wrong column is repaired only when an actual table schema proves the replacement instead of being guessed. Authentication rides on the Azure CLI login you already have, which is why there is nothing to set up — and also why every tool call runs with your identity, so a shared HTTP deployment stays on loopback unless you open it deliberately.

What it is

Two tools over Azure Data Explorer. One discovers, caches and explores cluster schemas; the other writes KQL from a natural-language question or runs the KQL you already have, validated against that cached schema before it executes.

What you get

KQL generated from a plain-English question, grounded in the discovered schema rather than guessed at
Raw KQL executed as written when you already know the query you want
Schema validation before execution, with an invalid column repaired only when a real table schema proves the replacement
Cluster schemas discovered once and cached, with tables listed and ranked context returned per table
Results as JSON, CSV or a table, with visualisations generated on request
Cache management — refresh or clear — and statistics on what has been cached so far

Requirements

Python 3.10 or higher, the Azure CLI installed, and access to an Azure Data Explorer cluster. Nothing to configure: the server checks your Azure CLI token at startup, runs an interactive az login only if it has to, and creates its own memory directory under %APPDATA%\KQL_MCP or ~/.local/share/KQL_MCP. pip install mcp-kql-server, then launch it as python -m mcp_kql_server over stdio. To share one process across several clients, run it with --transport http --host 127.0.0.1 --port 8000 --http-path /mcp --stateless-http; the bind stays on loopback because every tool call executes as your Azure CLI identity, and a non-loopback bind needs MCP_KQL_ALLOW_UNAUTHENTICATED_REMOTE_HTTP set to true on purpose. MCP_KQL_AUTH_MODE switches to managed-identity where that suits better, and responses are bounded by MCP_KQL_MAX_RESULT_ROWS, which defaults to 10000.

Setup effort

One command — pip install mcp-kql-server

See installation options

USE CASES

01

Asking a question of a cluster you do not know

Discover and cache the schema first, then have the query generated against it rather than from the model's memory.

kql_schema_memoryexecute_kql_query

02

Running a query you have already written

Execute the KQL as written and take the results back as JSON, CSV or a table.

execute_kql_query

03

Finding out what is in this database at all

List the tables, then read the ranked context for the ones that look relevant.

kql_schema_memory

04

Getting a chart out of the answer

Ask for the visualisation alongside the result instead of exporting and plotting it somewhere else.

execute_kql_query

05

Dealing with a schema that has moved on

Refresh or clear the cached schema so the next generated query matches what the cluster holds now.

kql_schema_memory

2 tools

Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.

`execute_kql_query`

Run KQL on Azure Data Explorer (Kusto) and return results.

Use this tool ANY time the user asks a question that needs data from a Kusto cluster (Azure Data Explorer, Azure Monitor Logs, Microsoft Sentinel, Defender XDR Advanced Hunting, or any *.kusto.windows.net endpoint).

Two modes:

Direct KQL: pass a real KQL query, leave generate_query=false.
Natural language to KQL: pass an English question and set generate_query=true. The query is grounded against the cached schema, validated, dry-run against ADX (| take 0), and self-repaired once on schema drift before execution.

Tips for the model:

If the user already gave you a query in cluster('x').database('y').T form, you can omit cluster_url and database; they will be parsed from the query.
For NL2KQL, call kql_schema_memory (operation=list_tables then discover) FIRST so the generator has accurate table/column context.
Default output is compact JSON. Use output_format="csv" for export and "table" for human-readable preview.

Args: query: KQL query, or a natural-language description if generate_query=true. cluster_url: Kusto cluster URL, e.g. https://help.kusto.windows.net. Optional if the query already embeds cluster(...).database(...). database: Database name. Optional if the query already embeds it. output_format: One of json (default), csv, table, generation_only. generate_query: If true, treat query as natural language and convert to KQL before execution. table_name: Optional hint for NL2KQL to bias generation toward a specific table. use_live_schema: When true (default) refresh the table schema from ADX before generation if the cache is stale.

Returns: JSON string. On success contains data, columns, row_count. On failure contains error, error_class, and recovery suggestions. Authentication: Uses the Azure authentication established at server startup; tool execution never launches an interactive login and tokens are never stored. Default query timeout: 2 minutes. Hard server-side ceiling: 10 minutes.

BEFORE YOU INSTALL

What to know first

Tools you get

2 tools when we connected. Both tools cover many operations: kql_schema_memory handles schema discovery and caching, and execute_kql_query handles natural-language-to-KQL generation, execution and output formats.

Requires

Python 3.10 or later

CONTEXT COST

Light Standing cost

Rated by the size of the 2 tool definitions that ride along on every turn, not by how many there are

INSTALLATION

Connect your client

Server setup

TERMINAL

pip install mcp-kql-server

MCP Clients

Claude Desktop

CLAUDE DESKTOP · JSON

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

VS Code

On macOS / Linux the command is "python3" instead of "py", without the "-3" arg.

VS CODE · 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"
      }
    }
  }
}

Roo Code, Cline

JSON

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

VS Code — Shared HTTP

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

VS CODE — SHARED HTTP · TERMINAL

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

Client configuration (VS Code mcp.json format)

VS CODE — SHARED HTTP · JSON

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

KQL Query Execution

Natural-language KQL that is checked against the real schema before it runs.

What it is

What you get

Requirements

Setup effort

Asking a question of a cluster you do not know

Running a query you have already written

Finding out what is in this database at all

Getting a chart out of the answer

Dealing with a schema that has moved on

2 tools

`execute_kql_query`

`kql_schema_memory`

What to know first

Tools you get

Requires

Light Standing cost

Connect your client

Server setup

MCP Clients

Claude Desktop

VS Code

Roo Code, Cline

VS Code — Shared HTTP

KQL Query Execution

Natural-language KQL that is checked against the real schema before it runs.

What it is

What you get

Requirements

Setup effort

Asking a question of a cluster you do not know

Running a query you have already written

Finding out what is in this database at all

Getting a chart out of the answer

Dealing with a schema that has moved on

2 tools

execute_kql_query

kql_schema_memory

What to know first

Tools you get

Requires

Light Standing cost

Connect your client

Server setup

MCP Clients

Claude Desktop

VS Code

Roo Code, Cline

VS Code — Shared HTTP

Same category

PostgreSQL Read-Only Query

Database Server

ThinAir Data

Turso Cloud

`execute_kql_query`

`kql_schema_memory`