kusto-mcp

Natural Language to Kusto Query MCP Server

A configurable MCP server that can convert natural language into kusto queries and execute the query against kusto database.

Features

• Fully configurable: provide a settings.yaml file to give the kusto query generator the data it needs to generate queries against any database
• Generate: returns a kusto query based on the given natural language prompt
• Execute: generate and execute a query based on the given natural language prompt. Output responses as JSON or in a CSV file
• Multiple databases: configure multiple databases in settings.yaml

Tools

• list-supported-tables
  • Lists the supported tables as provided in the settings.yaml file
• generate-kusto-query
  • Generates a kusto query against the provided table for the given prompt
  • Inputs:
    • parameters: an object containing the following parameters:
      • table (string): name of the table as configured in the settings.yaml file
      • category (string): category of the table as configured in the settings.yaml file
      • prompt (string): natural language prompt to execute against the provided database
• execute-kusto-query
• Generates a kusto query against the provided table for the given prompt
• Inputs:
  • parameters: an object containing the following parameters:
    • table (string): name of the table as configured in the settings.yaml file
    • category (string): category of the table as configured in the settings.yaml file
    • prompt (string): natural language prompt to execute against the provided database
    • outputType ('Json' or 'CSV'): output type for the response

Configuration

This project is designed to interact with Kusto databases and provides tools for querying and managing resources. Below are the steps to configure the project using the settings.yaml file.

Configuration File: settings.yaml

The MCP server takes in a --settings argument that should point to a yaml file configured as follows:

Environment variable references

You can configure references to environment variables in your settings.yaml file by using the ${{ENVIRONMENT_VARIABLE_NAME}} syntax.

Model Configuration

model:
  endpoint: <Azure OpenAI Endpoint>
  deployment: <Deployment Name>
  key: <Azure Open AI key>

• endpoint: The Azure OpenAI endpoint URL.
• deployment: The name of the deployment to use.
• key (optional): An optional key for the given Azure OpenAI endpoint. If a key is not provided, the tool will attempt to use the default azure credentials to execute on behalf of the user. This fallback currently only works if you run the server using dotnet run instead of docker run, and only inside of vs code.

Kusto Configuration

kusto:
  - name: <Table Name>
    category: <Category>
    database: <Database Name>
    table: <Table Name>
    endpoint: <Kusto Endpoint>
    accessToken: <Access Token>
    prompts:
      - type: <Prompt Type>
        content: |
          <Prompt Content>

• name: The name of the Kusto table.
• category: The category of the Kusto table (e.g., managedlabs).
• database: The name of the Kusto database.
• table: The name of the table in the Kusto database.
• endpoint: The Kusto endpoint URL.
• accessToken (optional): An optional user access token that can be used to connect to the given kusto database. If an access token is not provided, the tool will attempt to use the default azure credentials to execute on behalf of the user. This fallback currently only works if you run the server using dotnet run instead of docker run, and only inside of vs code. To generate an access token for a kusto database, you can run the following:

  az login
  az account get-access-token --resource "your-kusto-database-url" --query "accessToken"
  

• prompts: A list of prompts used for querying the Kusto database.
  • type: The type of the prompt (e.g., system, user, assistant).
  • content: The content of the prompt, which can include KQL queries and explanations.

Example Configuration

Below is an example configuration for the settings.yaml file:

model:
  endpoint: https://my-oai-resource.openai.azure.com
  deployment: my-deployment
  key: ${{ AZURE_OPENAI_KEY }}

kusto:
  - name: mytable
    category: mycategory
    database: mydatabase
    table: table
    endpoint: https://table.kusto.windows.net
    accessToken: ${{ MYTABLE_KUSTO_ACCESS_TOKEN }}
    prompts:
      - type: system
        content: |
          The table contains the following columns:
          * Id: id of the resource
          * Name: name of the resource
          * CreationTime: timestamp when the resource was created
          * LastModified: timestamp when the resource was last modified
          * Owner: owner of the resource
      - type: user
        content: When was the resource 'my resource' created in mycategory/mytable?
      - type: assistant
        content: |
          table
          | where name == 'my resource'
          | project CreationTime
      - type: user
        content: How many resources were created after April 1st, 2025?
      - type: assistant
        content: |
          table
          | where CreationTime > datetime(2025-04-01)
          | summarize count()
      - type: user
        content: Which owner owns the most resources in mycategory/mytable?
      - type: assistant
        content: |
          table
          | summarize Resources=count() by Owner
          | order by Resources desc
          | take 1
          | project Owner

Notes

• Ensure that the endpoint URLs are correct and accessible. Authentication is done via the currently logged in user in Windows. You may need to run az login or ensure that you are logged into to VSCode/VS to be able to authenticate
• Update the prompts section with relevant queries and explanations as needed. The more descriptive the better.
• Use the example configuration as a template to set up your own settings.yaml file.

Usage with VS Code

Add this to your .vscode/mcp.json:

{
  "inputs": [
    {
        "type": "promptString",
        "id": "azure-open-ai-key",
        "description": "Enter your Azure OpenAI key",
        "password": true
    },
    {
        "type": "promptString",
        "id": "kusto-token",
        "description": "Enter your Kusto token",
        "password": true
    }
  ],
  "kusto": {
    "type": "stdio",
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/settings.yaml:/app/settings.yaml", // Enter path to settings.yaml file. Can use vscode variables
        // Include environment variables that are references in settings.yaml file
        "-e",
        "AZURE_OPENAI_KEY",
        "-e",
        "KUSTO_ACCESS_TOKEN",
        "alexeyler/kusto-mcp-server",
    ],
    "env": {
        "AZURE_OPENAI_KEY": "${input:azure-open-ai-key}",
        "KUSTO_ACCESS_TOKEN": "${input:kusto-token}",
    }
  }
}

Build

From repo root: docker build ./src/Server/Dockerfile src