# 🔍 Kusto MCP Server

[![CI](https://github.com/johnib/kusto-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/johnib/kusto-mcp/actions/workflows/ci.yml)
[![npm version](https://badge.fury.io/js/kusto-mcp.svg)](https://badge.fury.io/js/kusto-mcp)
[![npm downloads](https://img.shields.io/npm/dm/kusto-mcp.svg)](https://www.npmjs.com/package/kusto-mcp)
[![Kusto MCP on mcprush](https://mcprush.com/badge/kusto-mcp/score.svg)](https://mcprush.com/to/kusto-mcp?ref=badge)

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

## Quick Setup

### For Claude Code Users

Run this terminal command to install:

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

### For GitHub Copilot CLI Users

Run this terminal command to install:

```bash
copilot mcp add kusto-mcp -- npx -y kusto-mcp@latest
```

Or add this to `~/.copilot/mcp-config.json`:

```json
{
  "mcpServers": {
    "kusto-mcp": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "kusto-mcp@latest"],
      "env": {},
      "tools": ["*"]
    }
  }
}
```

### For VS Code Users (Copilot Chat)

Add this to `.vscode/mcp.json` in your workspace, or to your user `mcp.json` (Command Palette → **MCP: Open User Configuration**):

```json
{
  "servers": {
    "kusto-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kusto-mcp@latest"]
    }
  }
}
```

### For Cline Users

Add this to your `cline_mcp_settings.json` file:

```json
{
  "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`:

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

### For Claude Desktop Users

Add this to your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "kusto-mcp": {
      "command": "npx",
      "args": ["-y", "kusto-mcp@latest"]
    }
  }
}
```

> **Long-running queries?** Some hosts have their own per-server tool timeout that can cut a slow query off before kusto-mcp does. Where the host supports it, raise it — e.g. `copilot mcp add --timeout <ms>` in Copilot CLI, or the `timeout` field (seconds) in Cline.

## Authentication Setup

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

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

2. **Login to Azure**:

   ```bash
   az login
   ```

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

**How sign-in works.** By default the server uses Azure's standard credential chain (`DefaultAzureCredential`): environment-variable service principals, workload or managed identity, then the Azure CLI (`az`), Azure PowerShell and the Azure Developer CLI. On a developer machine that normally means your `az login`. Set `KUSTO_AUTH_METHOD=azure-cli` to use only the Azure CLI. The CLI is asked for a token from your account's home tenant; if your cluster is in another tenant, set `AZURE_TENANT_ID` (see [Choosing the tenant](docs/CONFIGURATION.md#choosing-the-tenant)).

## Test It Works

Ask your AI assistant:

> "Connect to my Azure Data Explorer cluster at `https://your-cluster.kusto.windows.net`, database `YourDatabase`, 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
- ✅ **GitHub Copilot CLI** - One-command setup with native MCP support
- ✅ **VS Code (Copilot Chat)** - Native MCP support via `mcp.json`
- ✅ **Cline** - Full support with auto-approval
- ✅ **Cursor** - Complete integration
- ✅ **Claude Desktop** - Native MCP support
- ✅ **Any MCP-compatible tool** - Universal support

## Common Issues

A failed connect names the step that failed and one fix. The common ones:

| Message says | What to do |
| --- | --- |
| Azure CLI is not installed or not on PATH | Install it (`winget install Microsoft.AzureCLI`), run `az login`, restart your AI tool |
| Azure CLI is not signed in | Run `az login` |
| Azure CLI is signed in but has no default subscription | Run `az account list`, then `az account set --subscription <id>` |
| Your Azure sign-in expired or was revoked / needs MFA | Run `az login` again |
| Azure CLI did not return a token in time | Run `az account get-access-token --resource https://kusto.kusto.windows.net` to see how long it takes; raise `KUSTO_CONNECTION_TIMEOUT` (ms) if it is slow |
| rejected your token (HTTP 401) / not in the cluster's tenant | Set `AZURE_TENANT_ID` to the cluster's tenant id in the MCP server env |
| You are signed in but have no access (HTTP 403) | Ask the database admin for the Viewer role |
| rejected the request (HTTP 400) | Check the database name; names are case-sensitive |
| Can't resolve the cluster host / refused the connection | Check the cluster URL, VPN and proxy |
| Config warning: … | A setting was not valid and its default was used; fix the named setting |

**❓ 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](https://github.com/johnib/kusto-mcp/issues) or check our [troubleshooting guide](docs/CONFIGURATION.md#troubleshooting-configuration).

## 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 through Azure's standard credential chain (Azure CLI on a developer machine)
- 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.

Since 1.18.1, Azure tokens are cached, so a typical query runs about 4x faster (median ~3.5s → ~0.9s).

## 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 — apart from an optional `purpose` hint an assistant may add (details below).

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

- **Usage:** which tools are called, latency, query/command length (not text), requested row limit (and whether one was set), result row counts, response sizes, outcomes (including calls rejected for invalid arguments), and your config/feature-flag settings — for the cluster URL, auth method and connection timeout only whether each is unset, valid or invalid, never the value.
- **Declared purpose:** the optional `purpose` hint on `execute-query`; off-list values are sent as written (up to 512 characters).
- **Reliability:** call/error counts, connection attempts/failures, error **class names** (e.g. `KustoQueryError`), a fixed failure category (e.g. `query_semantic`, `throttled`, `timeout`, `not_connected`) and the HTTP status code of a failed query — never error messages. For connection attempts: which step failed (cloud metadata, token, or validation query) and how long it ran, how many token fetches and cache hits it took, which kind of credential produced the token (e.g. `az`, `mi`, `env`), the Kusto error code from a fixed list (anything else is sent as `other`), and whether the cluster host was reachable.
- **Session signals:** per-query bounded buckets of how the session is going — what the previous query's outcome was (e.g. `after_error`, `after_timeout`, `after_empty`), how many queries failed in a row (`0`–`5+`), which built-in hint, if any, was added to the response, and, when the previous query is still running, the outcome of the last one that finished.
- **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 (a known product name such as `claude-code`, otherwise `other`), a random per-install identifier (`machine.id`) and whether it could be saved, and how long after startup the MCP client finished its handshake.

**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. The one exception is the optional `purpose` hint on `execute-query`: when it isn't one of the listed labels, it is sent as written.

**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](docs/CONFIGURATION.md) for:

- Response format options (JSON vs Markdown)
- Query timeout settings (default 120s; your MCP host may have its own per-server timeout)
- Result size limiting
- OpenTelemetry integration

## For Developers

Building, testing, or contributing? See our [Developer Documentation](docs/DEVELOPER.md) for:

- Building from source
- Running tests
- Project structure
- Contributing guidelines

## License

[MIT](LICENSE)

---

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