# 🔍 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)

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

## 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
- ✅ **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

**🔒 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](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 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.

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