A Model Context Protocol (MCP) server that connects to Azure Kusto, enabling AI assistants to explore data schemas and execute KQL queries.
- Azure Kusto Integration: Connect securely to Azure Kusto clusters
- Schema Exploration: Expose table schemas as resources for AI assistants
- Query Execution: Tools for running KQL queries and analyzing results
- Data Analysis Assistance: Built-in prompts for common data analysis tasks
- VS Code Integration: Configures connection details interactively within VS Code
- Python 3.9+
- Azure Kusto cluster access
- VS Code with GitHub Copilot or Copilot Chat extension (for MCP support)
- Required Python packages (installed automatically with setup script)
The easiest way to set up the MCP server with VS Code integration:
python setup-mcp.py
This script will:
- Install all required dependencies
- Create the necessary configuration for VS Code integration
- Provide instructions for starting the server
- Clone the repository:
git clone https://github.com/yourusername/kusto-mcp-server.git
cd kusto-mcp-server
- Install the required dependencies:
pip install -r requirements.txt
- (Optional) Configure environment variables:
Create a
.envfile in the root directory with the following variables:
AZURE_KUSTO_CLUSTER=https://<your-cluster>.kusto.windows.net
AZURE_KUSTO_DATABASE=<your-database>
The mcp.json file is required to configure the MCP server with VS Code. If you're setting up manually or the setup script didn't create this file, follow these steps:
- Create a new file named
mcp.jsonin the.vscodedirectory of your workspace (create this directory if it doesn't exist) - Add the following content to the file:
{
"inputs": [
{
"type": "promptString",
"id": "kusto-cluster",
"description": "Azure Kusto Cluster URL (e.g., https://mycluster.kusto.windows.net)",
"default": ""
},
{
"type": "promptString",
"id": "kusto-database",
"description": "Azure Kusto Database Name",
"default": ""
}
],
"servers": {
"Azure Kusto MCP": {
"type": "stdio",
"command": "${command:python.interpreterPath}",
"args"
8000
: ["${workspaceFolder}/src/kusto_mcp/server.py"],
"env": {
"AZURE_KUSTO_CLUSTER": "${input:kusto-cluster}",
"AZURE_KUSTO_DATABASE": "${input:kusto-database}",
"PYTHONPATH": "${workspaceFolder}"
}
}
}
}- If needed, customize the configuration:
- Change the
commandif you need to use a specific Python interpreter path - Modify the
argsif your server script is located elsewhere - Add additional environment variables if required
- Note that
${workspaceFolder}and${command:python.interpreterPath}are VS Code variables that will be automatically replaced with the appropriate paths
- Change the
This configuration includes input prompts that will ask for your Kusto cluster URL and database name each time you start the server, making it easy to switch between different databases.
To use the MCP server with VS Code:
- Make sure you've run the setup script:
python setup-mcp.pyor manually created themcp.jsonfile - Install the GitHub Copilot or Copilot Chat extension in VS Code
- Open the Command Palette (Ctrl+Shift+P)
- Run "MCP: Start Server with Configuration"
- Select "Azure Kusto MCP" from the list
- Enter your Kusto cluster URL and database name when prompted
The MCP server will start and connect to your Copilot Chat session, allowing you to:
- Connect to your Kusto cluster using the
connecttool - Browse table schemas
- Execute queries
- Analyze data
Start the MCP server directly with:
python -m src.kusto_mcp.server
If you haven't configured the connection in the .env file, the server will prompt you for connection details when needed.
This server uses Azure's DefaultAzureCredential for authentication, which supports:
- Environment variables
- Managed Identity
- Azure CLI credentials
- Azure PowerShell credentials
- Interactive browser authentication as a fallback
Make sure you're authenticated with at least one of these methods before connecting.
The server exposes the following resources:
kusto/tables- List of all tables in the current databasekusto/schema/{table_name}- Schema for a specific tablekusto/sample- Sample KQL query and explanationkusto/connection- Current connection information
The following tools are available:
connect- Connect to a Kusto cluster and databaseconnection_status- Check the current connection statusexecute_query- Run a KQL queryanalyze_data- Execute a query and analyze the resultsoptimize_query- Get suggestions for query optimization
The Kusto MCP server provides several tools for interacting with Azure Kusto. Here's how to use each tool effectively:
The connect tool establishes a connection to an Azure Kusto cluster and database.
Usage in Copilot Chat:
I need to connect to my Kusto cluster
This tool will prompt you for:
- The cluster URL (e.g., https://yourcluster.kusto.windows.net)
- The database name
Authentication is handled automatically via Azure's DefaultAzureCredential.
Example:
Connect to the Kusto database named "MyDatabase" on the cluster "analytics.kusto.windows.net"
The connection_status tool shows your current connection details.
Usage in Copilot Chat:
Check my current Kusto connection
Example Output:
✅ Connected to Azure Kusto.
- **Cluster**: https://analytics.kusto.windows.net
- **Database**: MyDatabase
The execute_query tool runs KQL queries against your connected database.
Usage in Copilot Chat:
Run this KQL query: <your query here>
Example:
Run this KQL query: StormEvents | where State == "FLORIDA" | take 10
For large result sets (>100 rows), the tool will return a summary and the first 10 rows.
The analyze_data tool executes a query and performs analysis on the results.
Usage in Copilot Chat:
Analyze this query: <your query here>
You can specify an analysis type:
summary(default): Basic statistics about the datastats: Detailed statistical analysis including correlationsplot_ready: Information to help visualize the data
Example:
Analyze this query with stats analysis: StormEvents | summarize count() by State | top 10 by count_
The optimize_query tool provides suggestions to improve your KQL queries.
Usage in Copilot Chat:
Optimize this KQL query: <your query here>
Example:
Optimize this KQL query:
StormEvents
| project *
| where StartTime > ago(7d)
| sort by StartTime desc
To explore available tables and their schemas:
What tables are available in this database?
To examine a specific table's schema:
Show me the schema for the StormEvents table
For time-based data analysis:
Help me analyze time trends in the StormEvents table using the StartTime column
To find relationships between columns:
Find correlations between DamageProperty and DeathsDirect in the StormEvents table
To verify data quality:
Check for null values and outliers in the StormEvents table
For complex queries, you can ask for guidance:
I need to build a query that shows storm events by state, with damage amounts, limited to the top 10 most expensive events. Can you help me construct this?
- Always connect first: Use the
connecttool before attempting to run queries - Verify connections: Use the
connection_statustool if you're unsure about your connection state - Start with small queries: Use
takeorlimitoperators to test queries before running on large datasets - Use analysis tools: The
analyze_datatool provides valuable insights with minimal effort - Ask for optimization: Use the
optimize_querytool for long-running or complex queries
Here are some example KQL queries to get you started:
// Simple filtering
StormEvents
| where State == "FLORIDA"
| take 10
// Aggregation
StormEvents
| summarize EventCount=count() by State
| order by EventCount desc
| take 10
// Time filtering
StormEvents
| where StartTime > ago(30d)
| summarize EventCount=count() by bin(StartTime, 1d)
| render timechart
// Join example
StormEvents
| where EventType == "Tornado"
| join (
StormEvents
| where EventType == "Flood"
| project State, FloodTime=StartTime
) on State
| project State, TornadoTime=StartTime, FloodTime
| take 10If you're having issues with the MCP configuration:
- Missing mcp.json: Create the file manually in the
.vscodedirectory as described above - Configuration not showing: Ensure the
mcp.jsonfile is properly formatted and located in the.vscodedirectory - Server not connecting: Check that the hostname and port specified in the
mcp.jsonfile are available - Copilot not detecting server: Restart VS Code after creating or modifying the
mcp.jsonfile
In addition to the general troubleshooting tips mentioned earlier, here are specific solutions for common tool issues:
- Error: "Failed to connect": Verify your Azure credentials are valid and you have access to the specified cluster and database
- Timeout errors: Check your network connection and firewall settings
- Authentication failures: Ensure you're logged into Azure with
az loginor have valid environment credentials
- Timeout on large queries: Add filters or time constraints to reduce the data volume
- Syntax errors: Use the
optimize_querytool to check and fix your query syntax - Missing columns: Verify column names using schema exploration before querying
- Empty analysis results: Ensure your query returns data before analyzing
- Correlation errors: Check that your data contains at least two numeric columns for correlation analysis
- Visualization preparation: For
plot_readyanalysis, include both categorical and numeric columns for best results
This MCP server is designed to work with AI assistants that support the Model Context Protocol. The server provides structured access to Azure Kusto data, allowing AI assistants to:
- Browse available tables and schemas
- Execute read-only KQL queries
- Analyze query results
- Provide guidance on data analysis
- The server uses Azure's DefaultAzureCredential for secure authentication
- Only users with appropriate permissions can access the Kusto cluster
- Credentials are never stored by the server itself
MIT License