@aditya-vaish/kusto-mcp-server/README.md

MCP server for interacting with Kusto databases

# Kusto MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that connects to your Azure Data Explorer (Kusto) database, exposing table schemas as resources and providing tools for data analysis.

## Features

- **Connection to Kusto Database**: Securely connects to your Azure Data Explorer environment using service principal or managed identity authentication.
- **Schema Resources**: Exposes table schemas and sample data as resources for AI assistants to understand your data structure.
- **KQL Query Tools**: Provides tools for running read-only KQL queries against your database.
- **Data Analysis Tools**: Pre-built tools for common data analysis tasks like time series analysis, anomaly detection, etc.
- **Analysis Prompts**: Includes prompt templates for guiding AI assistants in performing common data analysis tasks.

## Setup Instructions

### Prerequisites

- Node.js 18.0 or higher
- Access to an Azure Data Explorer (Kusto) database
- Proper authentication credentials (service principal or managed identity)

### Installation

1. Clone this repository or navigate to the project directory
2. Install dependencies:

```bash
npm install
```

3. Create a `.env` file based on the example:

```bash
cp .env.example .env
```

4. Configure the environment variables in the `.env` file:

```
# Kusto Connection Settings
KUSTO_CLUSTER_URI=https://your-cluster.kusto.windows.net
KUSTO_DATABASE=your-database

# Authentication settings 
# Option 1: Azure AD App Registration (Service Principal)
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id

# Option 2: Managed Identity (if running in Azure)
# USE_MANAGED_IDENTITY=true

# MCP Server Config
MCP_SERVER_NAME=kusto-mcp-server
MCP_SERVER_VERSION=1.0.0
```

### Build and Run

1. Build the TypeScript project:

```bash
npm run build
```

2. Start the MCP server:

```bash
npm start
```

## Integrating with MCP Clients

### Using with Claude Desktop

1. Configure Claude Desktop to use this MCP server by adding it to your `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "kusto-server": {
      "command": "node",
      "args": [
        "path/to/kusto-mcp-server/dist/index.js"
      ]
    }
  }
}
```

2. Start Claude Desktop and the server will automatically connect.

### Using with Other MCP Clients

This MCP server uses the standard stdio transport, making it compatible with any MCP client that supports this transport.

## Available Resources

- `kusto://tables` - Lists all available tables in the database
- `kusto://schema/{tableName}` - Shows schema information for a specific table
- `kusto://sample/{tableName}/{sampleSize?}` - Retrieves sample data from a specific table

## Available Tools

- `executeQuery` - Executes a read-only KQL query against your database
- `getTableInfo` - Gets detailed schema and sample data for a specified table
- `findTables` - Finds tables that match a specified name pattern
- `analyzeData` - Performs various data analyses including summary statistics, time series analysis, top values analysis, outlier detection, and correlation analysis

## Available Prompts

- **Explore Dataset** - Guide for exploring a new dataset 
- **Time Series Analysis** - Analyze trends and patterns in time-based data
- **Anomaly Detection** - Identify unusual patterns or outliers in data
- **Comparative Analysis** - Compare data across different dimensions or time periods
- **KQL Query Assistance** - Get help building and optimizing KQL queries
- **Data Quality Assessment** - Evaluate and understand the quality of your data

## Security Considerations

- This server only allows read-only operations to protect your data
- Contains basic security measures to prevent destructive operations
- Uses Azure AD authentication for secure database access
- Consider additional security measures depending on your specific requirements

## License

ISC