Skip to main content
Glama
johnib

kusto-mcp

by johnib

πŸ” Kusto MCP Server

CI npm version npm downloads

Turn your AI assistant into a data analyst in 2 minutes.

Connect Cline, Cursor, Claude Desktop, or any AI tool to Azure Data Explorer. Ask questions in plain English, get insights from your data instantly - no KQL knowledge required.

What You Can Do

  • "Show me error logs from the last hour" β†’ Get instant insights from telemetry data

  • "Which customers generated the most revenue this month?" β†’ Analyze business metrics effortlessly

  • "Find all failed authentication attempts" β†’ Investigate security incidents with AI help

  • "Summarize system performance trends" β†’ Get automated analysis of monitoring data

No more writing complex KQL queries. Just ask your AI assistant natural questions about your data.

Related MCP server: MCP KQL Server

Quick Setup

For Claude Code Users

Run this terminal command to install:

claude mcp add kusto-mcp -- npx -y kusto-mcp@latest

For Cline Users

Add this to your cline_mcp_settings.json file:

{
  "mcpServers": {
    "github.com/johnib/kusto-mcp": {
      "command": "npx",
      "args": ["-y", "kusto-mcp@latest"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "initialize-connection",
        "show-tables",
        "show-table",
        "execute-query",
        "report-issue"
      ]
    }
  }
}

For Cursor Users

Add this to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "github.com/johnib/kusto-mcp": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "kusto-mcp"]
      }
    }
  }
}

For Claude Desktop Users

Add this to your Claude Desktop configuration file:

{
  "mcpServers": {
    "kusto-mcp": {
      "command": "npx",
      "args": ["-y", "kusto-mcp"]
    }
  }
}

Authentication Setup

  1. Install Azure CLI (if you haven't already):

    # Windows
    winget install Microsoft.AzureCLI
    
    # macOS
    brew install azure-cli
    
    # Linux
    curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
  2. Login to Azure:

    az login
  3. That's it! Your AI assistant can now connect to your Azure Data Explorer clusters.

Test It Works

Ask your AI assistant:

"Connect to my Azure Data Explorer cluster at https://your-cluster.kusto.windows.net and show me the available tables"

You should see your AI successfully connect and list your database tables.

Supported AI Tools

  • βœ… Claude Code - One-command setup with native MCP support

  • βœ… Cline - Full support with auto-approval

  • βœ… Cursor - Complete integration

  • βœ… Claude Desktop - Native MCP support

  • βœ… VS Code with MCP - Built-in compatibility

  • βœ… Any MCP-compatible tool - Universal support

Common Issues

πŸ”’ Permission denied?

  • Run az login and make sure you have access to the Azure Data Explorer cluster

  • Verify you're logged into the correct Azure tenant

πŸ”Œ Can't connect to cluster?

  • Double-check the cluster URL format: https://your-cluster.kusto.windows.net

  • Ensure the cluster is accessible from your network

❓ AI doesn't see the tools?

  • Restart your AI assistant after adding the configuration

  • Check that the JSON configuration is valid (use a JSON validator)

Still stuck? β†’ Open an issue or check our troubleshooting guide.

What's Under the Hood

This MCP server provides your AI assistant with tools to:

  • Initialize connections to Azure Data Explorer clusters

  • Browse database tables and schemas

  • Execute KQL queries with intelligent result limiting

  • Handle authentication securely through Azure CLI

  • Report a bug or request a feature on GitHub (report-issue)

Results are automatically formatted and sized appropriately for AI context windows, so your assistant gets the data it needs without being overwhelmed.

Reporting a Problem

Hit a bug or want a feature? Ask your AI assistant to "report a kusto-mcp issue about …" and it will call the report-issue tool.

The tool returns a pre-filled GitHub issue link β€” open it in a browser where you're signed in to GitHub, review the title and body, and click Submit new issue. A few things worth knowing:

  • No GitHub token is needed or stored. The server never files anything on your behalf; the issue is created under your own GitHub account when you submit the form. (You do need a GitHub account to submit.)

  • Works even when the connection is broken β€” it doesn't require an active Kusto connection, so it's the right tool for reporting connection problems.

  • By default a small, non-sensitive environment footer (kusto-mcp/Node/OS/MCP-client versions, whether a connection is active, response format, write mode) is appended to help triage. Pass includeDiagnostics: false to omit it. It never includes your cluster URL, database, identity, query text, or results.

Telemetry & Privacy

kusto-mcp reports anonymous usage telemetry to the maintainer's Honeycomb instance to understand how the tool is used and to diagnose failures. Telemetry is always on β€” using kusto-mcp means reporting anonymous usage. There is no personal or organizational data in it, and no query text or results (details below).

What is collected (traces, metrics, and operational logs via OpenTelemetry):

  • Usage: which tools are called, latency, query/command length (not text), result row counts, response sizes, outcomes, and your config/feature-flag settings.

  • Reliability: call/error counts, connection attempts/failures, and error class names (e.g. KustoQueryError) β€” never error messages.

  • Cohort counters: salted hashes of your Azure tenant id (company_hash) and object id (user_hash), so the maintainer can count distinct organizations and users β€” no raw tenant, company name, email domain, email, UPN, or user id is ever sent. Plus principal_type (user vs service principal) and account_type (personal vs enterprise); the shared personal-account tenant sends no company_hash.

  • Environment: kusto-mcp version, OS/architecture, Node.js version, MCP client name, and a random per-install identifier (machine.id).

What is NEVER collected: no company name or email domain; no raw Azure tenant id or user id; no full email, UPN, or name; no cluster, database, table, or function names; no query text, results, error messages, credentials, or tokens.

Routing to your own collector: enterprises that run their own OpenTelemetry pipeline can redirect the data with standard env vars β€” OTEL_EXPORTER_OTLP_ENDPOINT (your OTLP HTTP base URL) and OTEL_EXPORTER_OTLP_HEADERS (key=value,key2=value2).

Advanced Configuration

Need custom settings? Check out our Configuration Guide for:

  • Response format options (JSON vs Markdown)

  • Query timeout settings

  • Result size limiting

  • OpenTelemetry integration

For Developers

Building, testing, or contributing? See our Developer Documentation for:

  • Building from source

  • Running tests

  • Project structure

  • Contributing guidelines

License

MIT


πŸ’‘ Pro tip: Start by asking your AI to "show me the tables in my database" to explore what data you have available, then ask natural language questions about specific tables.

Available Tools

6 tools
execute-queryA

Runs KQL queries and returns results. By default, limits results to 20 rows to prevent context overflow. Use the "limit" parameter to specify a different maximum. If results are marked as partial, consider revising your query to use aggregations, filters, or summarizations.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitYesMaximum number of rows to return (default: 20)
queryYesThe query to execute

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the default row limit, the ability to override it, and the significance of partial results. This is good transparency for a query tool, though it does not mention idempotency or read-only nature (implied but not explicit).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each essential. The first states the main action, the second explains the default limit and how to change it, the third advises on partial results. No filler or redundancy. Properly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains the result limit and partial result handling. It is missing information on error handling, authentication, or query syntax specifics, but for a simple query tool, it covers the key behavioral aspects needed for correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with descriptions for both 'query' and 'limit'. The description adds context: 'By default, limits results to 20 rows to prevent context overflow. Use the 'limit' parameter to specify a different maximum.' This goes beyond the schema's 'Maximum number of rows (default: 20)' by explaining why the default exists and how to adjust.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Runs KQL queries and returns results,' specifying the verb ('Runs') and resource ('KQL queries'). It distinguishes from sibling tools like 'show-table' and 'initialize-connection', which serve different purposes. The purpose is unambiguous and specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides guidance on default behavior ('limits results to 20 rows'), how to adjust via the limit parameter, and what to do with partial results (revise query with aggregations). However, it does not explicitly state when to use this tool versus alternatives (e.g., show-table for schema), but context is clear enough for typical use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

initialize-connectionB

Creates connection to an ADX cluster

ParametersJSON Schema
NameRequiredDescriptionDefault
databaseYesThe database to connect to
cluster_urlYesThe URL of the Kusto cluster

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description lacks details about side effects, idempotency, error behavior, or resource lifecycleβ€”it simply says 'creates connection' without elaboration.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short (5 words) and lacks any structure; while concise, it omits important context that could be provided in a few more sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, no annotations, and the description fails to cover return values, connection state, or usage context beyond the basic action, making it incomplete for an agent to use reliably.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions, so the description adds no additional parameter meaning; baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a connection to an ADX cluster, distinguishing it from siblings like execute-query and show-table which perform different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites such as needing valid credentials or that this should be called before other tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

report-issueA

Report a bug or request a feature for kusto-mcp on GitHub. Returns a pre-filled GitHub issue link you open in your browser and submit under your own GitHub account β€” no GitHub token is used or stored, and no Kusto connection is required.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNoFull description (Markdown): what happened, expected vs actual behavior, and steps to reproduce.
titleYesShort summary line for the GitHub issue
labelsNoLabels to pre-select, e.g. ['bug'] or ['enhancement'].
includeDiagnosticsYesAppend non-sensitive environment info (kusto-mcp/node/OS/MCP-client versions, connection state, response format, write mode). Never includes cluster URL, database, identity, query text, or results.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that the tool returns a pre-filled link, requires user submission under own account, and details includeDiagnostics behavior. Could mention error handling, but sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences covering purpose, behavior, and key constraints. No wasted words; front-loaded with main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 params, no output schema, and no annotations, the description covers purpose, return value, and parameter nuances. Lacks error handling or fallback info, but complete enough for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. Description adds meaning by explaining the overall flow and elaborating on includeDiagnostics (what’s excluded). Provides context beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool reports bugs/features for kusto-mcp on GitHub, with clear verb 'Report' and resource. It distinguishes from sibling tools (execute-query, initialize-connection, etc.) which focus on Kusto operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for reporting issues without GitHub token or Kusto connection, but lacks explicit 'when to use' vs alternatives. Context from siblings makes differentiation clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

show-functionA

Show details of a specific function, including its code and parameters

ParametersJSON Schema
NameRequiredDescriptionDefault
functionNameYesThe name of the function to get details for

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the read-only nature (shows code and parameters) but omits details on error handling, response structure, or permissions. Adequate but minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that efficiently conveys the tool's purpose without unnecessary words. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description is nearly complete. It explains what the tool does and what details are returned. However, without an output schema, additional detail on the response format would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description of the single parameter 'functionName'. The description adds minimal extra value by stating the output includes 'code and parameters', but does not enhance understanding of the parameter itself. Baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('show details'), the resource ('a specific function'), and what is included ('code and parameters'). It effectively distinguishes from sibling tools like 'show-functions' which lists all functions, and 'show-table' which is for a different resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving details of a specific function but does not explicitly state when to use this over alternatives like 'show-functions' or provide any prerequisites or context. Guidance is missing, leaving the agent to infer context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

show-functionsB

List functions in the current database

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose any behavioral traits such as side effects, authentication requirements, rate limits, or return format. The description carries the full burden for transparency, and it fails to provide any.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that is front-loaded and contains no extraneous words. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no output schema, the description is minimal. It does not specify what the function returns, whether pagination exists, or any other behavioral details needed for an agent to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema coverage is 100%. With no parameters to describe, the baseline score of 4 applies as the description adds no meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'List functions in the current database', specifying the action (list) and resource (functions). It distinguishes from sibling tool 'show-function' which likely retrieves details of a single function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance provided on when to use this tool versus alternatives like 'show-function' or 'show-tables'. The description offers no exclusions or context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

show-tableB

Show the table schema columns

ParametersJSON Schema
NameRequiredDescriptionDefault
tableNameYesThe name of the table to get the schema for

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It only states a read operation without detailing potential behaviors like required permissions, performance impact, or return format. The minimal disclosure leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no redundant words. It front-loads the primary action and resource, efficiently communicating its purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one parameter, no output schema), the description is insufficiently complete. It omits what the output looks like (e.g., column names, types, constraints) and any side effects, leaving the agent with incomplete information for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents the required parameter 'tableName' with a description. The tool's description adds no additional meaning beyond what the schema offers, so a baseline score of 3 is appropriate for adequate but not enhanced parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Show the table schema columns' uses a specific verb and resource, clearly indicating the tool retrieves schema details for a given table. This distinguishes it from sibling tools like show-tables (list all tables) and show-function (function details).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites, context, or exclusions, leaving the agent to infer usage from tool names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A3.8/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: query execution, connection initialization, issue reporting, and four metadata exploration tools (list functions, function details, list tables, table schema). No overlap.

Naming Consistency5/5

All tools use a consistent verb_noun pattern (execute-query, initialize-connection, report-issue, show-function, show-functions, show-table, show-tables). Singular/plural variations for listing vs. detail tools are appropriate.

Tool Count5/5

Seven tools cover the essential operations for a Kusto query and metadata exploration server without unnecessary bloat. The count is well-scoped for the domain.

Completeness4/5

The tool surface covers core query execution, connection setup, and metadata browsing (tables, functions). Minor gaps exist (e.g., no ability to manage functions or tables), but for a query-focused MCP server this is reasonable.

Maintenance

ActivityActive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    B
    maintenance
    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.
    23
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to query and analyze data in Azure Data Explorer, Log Analytics, and Microsoft Sentinel using Kusto Query Language (KQL) through tools, resources, and prompts.
    5
    MIT

Latest Blog Posts

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/johnib/kusto-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server