# MCP KQL Server
[](https://mseep.ai/app/4r9un-mcp-kql-server)
> **AI-Powered KQL Query Execution with Intelligent Schema Memory**
A Model Context Protocol (MCP) server that provides intelligent KQL (Kusto Query Language) query execution with AI-powered schema caching and context assistance for Azure Data Explorer clusters.
<!-- Badges Section -->
[](https://mseep.ai/app/18772353-3d90-4b12-a253-cf752efaadd2)
[](https://pypi.org/project/mcp-kql-server/)
[](https://pypi.org/project/mcp-kql-server/)
[](https://github.com/4R9UN/mcp-kql-server/actions)
[](https://codecov.io/gh/4R9UN/mcp-kql-server)
[](https://github.com/4R9UN/mcp-kql-server/security)
[](https://github.com/4R9UN/mcp-kql-server)
[](https://github.com/jlowin/fastmcp)
[](https://azure.microsoft.com/en-us/services/data-explorer/)
[](https://github.com/anthropics/mcp)
[](https://github.com/4R9UN/mcp-kql-server/graphs/commit-activity)
## 🚀 Features
- **🎯 Intelligent KQL Execution**: Execute KQL queries against any Azure Data Explorer cluster
- **🧠 AI Schema Memory**: Automatic schema discovery and intelligent caching
- **📊 Rich Visualizations**: Markdown table output with configurable formatting
- **⚡ Performance Optimized**: Smart caching reduces cluster API calls
- **🔐 Azure Authentication**: Seamless Azure CLI integration
- **🎨 Context-Aware**: AI-powered query assistance and error suggestions
- **🔕 Clean Output**: Suppressed FastMCP branding for professional experience (v2.0.2+)
## 📊 MCP Tools Execution Flow
### KQL Query Execution Flow
```mermaid
graph TD
A[👤 User Submits KQL Query] --> B{🔍 Query Validation}
B -->|❌ Invalid| C[📝 Syntax Error Response]
B -->|✅ Valid| D[🧠 Load Schema Context]
D --> E{💾 Schema Cache Available?}
E -->|✅ Yes| F[⚡ Load from Memory]
E -->|❌ No| G[🔍 Discover Schema]
F --> H[🎯 Execute Query]
G --> I[💾 Cache Schema + AI Context]
I --> H
H --> J{🎯 Query Success?}
J -->|❌ Error| K[🚨 Enhanced Error Message]
J -->|✅ Success| L[📊 Process Results]
L --> M[🎨 Generate Visualization]
M --> N[📤 Return Results + Context]
K --> O[💡 AI Suggestions]
O --> N
style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff
style B fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
style C fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff
style D fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
style F fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
style G fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
style H fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
style I fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
style J fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
style K fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff
style L fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
style M fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
style N fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
style O fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
```
### Schema Memory Discovery Flow
```mermaid
graph TD
A[👤 User Requests Schema Discovery] --> B[🔗 Connect to Cluster]
B --> C[📂 Enumerate Databases]
C --> D[📋 Discover Tables]
D --> E[🔍 Get Table Schemas]
E --> F[🤖 AI Analysis]
F --> G[📝 Generate Descriptions]
G --> H[💾 Store in Memory]
H --> I[📊 Update Statistics]
I --> J[✅ Return Summary]
style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff
style B fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
style C fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
style D fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
style F fill:#e67e22,stroke:#bf6516,stroke-width:2px,color:#ffffff
style G fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
style H fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
style I fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
style J fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
```
## 📋 Prerequisites
- Python 3.10 or higher
- Azure CLI installed and authenticated (`az login`)
- Access to Azure Data Explorer cluster(s)
## 🚀 One-Command Installation
### Quick Install (Recommended)
#### From Source
```bash
git clone https://github.com/4R9UN/mcp-kql-server.git && cd mcp-kql-server && pip install -e .
```
### Alternative Installation Methods
```bash
pip install mcp-kql-server
```
**That's it!** The server automatically:
- ✅ Sets up memory directories in `%APPDATA%\KQL_MCP` (Windows) or `~/.local/share/KQL_MCP` (Linux/Mac)
- ✅ Configures optimal defaults for production use
- ✅ Suppresses verbose Azure SDK logs
- ✅ No environment variables required
## 📱 MCP Client Configuration
### Claude Desktop
Add to your Claude Desktop MCP settings file (`mcp_settings.json`):
**Location:**
- **Windows**: `%APPDATA%\Claude\mcp_settings.json`
- **macOS**: `~/Library/Application Support/Claude/mcp_settings.json`
- **Linux**: `~/.config/Claude/mcp_settings.json`
```json
{
"mcpServers": {
"mcp-kql-server": {
"command": "python",
"args": ["-m", "mcp_kql_server"],
"env": {}
}
}
}
```
### VSCode (with MCP Extension)
Add to your VSCode MCP configuration:
**Settings.json location:**
- **Windows**: `%APPDATA%\Code\User\settings.json`
- **macOS**: `~/Library/Application Support/Code/User/settings.json`
- **Linux**: `~/.config/Code/User/settings.json`
```json
{
"mcp.servers": {
"mcp-kql-server": {
"command": "python",
"args": ["-m", "mcp_kql_server"],
"cwd": null,
"env": {}
}
}
}
```
### Roo-code (Cline Extension)
Add to your Roo-code MCP settings:
**MCP Settings location:**
- **All platforms**: Through Roo-code extension settings or `mcp_settings.json`
```json
{
"mcpServers": {
"kql-server": {
"command": "python",
"args": ["-m", "mcp_kql_server"],
"env": {},
"description": "KQL Server for Azure Data Explorer queries with AI assistance"
}
}
}
```
### Generic MCP Client
For any MCP-compatible application:
```bash
# Command to run the server
python -m mcp_kql_server
# Server provides these tools:
# - kql_execute: Execute KQL queries with AI context
# - kql_schema_memory: Discover and cache cluster schemas
```
### Configuration with Environment Variables
You can customize the server behavior with environment variables:
```json
{
"mcpServers": {
"mcp-kql-server": {
"command": "python",
"args": ["-m", "mcp_kql_server"],
"env": {
}
}
}
}
```
## 🔧 Quick Start
### 1. Authenticate with Azure (One-time setup)
```bash
az login
```
### 2. Start the MCP Server (Zero configuration)
```bash
python -m mcp_kql_server
```
The server starts immediately with:
- 📁 **Auto-created memory path**: `%APPDATA%\KQL_MCP\cluster_memory`
- 🔧 **Optimized defaults**: No configuration files needed
- 🔐 **Secure setup**: Uses your existing Azure CLI credentials
### 3. Use via MCP Client
The server provides two main tools:
> #### `kql_execute` - Execute KQL Queries with AI Context
> #### `kql_schema_memory` - Discover and Cache Cluster Schemas
## 💡 Usage Examples
### Basic Query Execution
Ask your MCP client (like Claude):
> "Execute this KQL query against the help cluster: `cluster('help.kusto.windows.net').database('Samples').StormEvents | take 10` and summarize the result and give me high level insights "
### Complex Analytics Query
Ask your MCP client:
> "Query the Samples database in the help cluster to show me the top 10 states by storm event count, include visualization"
### Schema Discovery
Ask your MCP client:
> "Discover and cache the schema for the help.kusto.windows.net cluster, then tell me what databases and tables are available"
### Data Exploration with Context
Ask your MCP client:
> "Using the StormEvents table in the Samples database on help cluster, show me all tornado events from 2007 with damage estimates over $1M"
### Time-based Analysis
Ask your MCP client:
> "Analyze storm events by month for the year 2007 in the StormEvents table, group by event type and show as a visualization"
## 🎯 Key Benefits
### For Data Analysts
- **⚡ Faster Query Development**: AI-powered autocomplete and suggestions
- **🎨 Rich Visualizations**: Instant markdown tables for data exploration
- **🧠 Context Awareness**: Understand your data structure without documentation
### For DevOps Teams
- **🔄 Automated Schema Discovery**: Keep schema information up-to-date
- **💾 Smart Caching**: Reduce API calls and improve performance
- **🔐 Secure Authentication**: Leverage existing Azure CLI credentials
### For AI Applications
- **🤖 Intelligent Query Assistance**: AI-generated table descriptions and suggestions
- **📊 Structured Data Access**: Clean, typed responses for downstream processing
- **🎯 Context-Aware Responses**: Rich metadata for better AI decision making
## 🏗️ Architecture
```mermaid
graph TD
A[MCP Client<br/>Claude/AI/Custom] <--> B[MCP KQL Server<br/>FastMCP Framework]
B <--> C[Azure Data Explorer<br/>Kusto Clusters]
B <--> D[Schema Memory<br/>Local AI Cache]
style A fill:#4a90e2,stroke:#2c5282,stroke-width:3px,color:#ffffff
style B fill:#8e44ad,stroke:#6a1b99,stroke-width:3px,color:#ffffff
style C fill:#e67e22,stroke:#bf6516,stroke-width:3px,color:#ffffff
style D fill:#27ae60,stroke:#1e8449,stroke-width:3px,color:#ffffff
```
## 📁 Project Structure
```
mcp-kql-server/
├── mcp_kql_server/
│ ├── __init__.py # Package initialization
│ ├── mcp_server.py # Main MCP server implementation
│ ├── execute_kql.py # KQL query execution logic
│ ├── schema_memory.py # Schema caching and discovery
│ ├── unified_memory.py # Advanced memory management
│ ├── kql_auth.py # Azure authentication
│ ├── utils.py # Utility functions
│ └── constants.py # Configuration constants
├── docs/ # Documentation
├── Example/ # Usage examples
├── pyproject.toml # Project configuration
└── README.md # This file
```
## 🚀 Advanced Usage
### Custom Memory Path
```python
{
"tool": "kql_execute",
"input": {
"query": "...",
"cluster_memory_path": "/custom/memory/path"
}
}
```
### Force Schema Refresh
```python
{
"tool": "kql_schema_memory",
"input": {
"cluster_uri": "mycluster",
"force_refresh": true
}
}
```
### Performance Optimization
```python
{
"tool": "kql_execute",
"input": {
"query": "...",
"use_schema_context": false, # Disable for faster execution
"visualize": false # Disable for minimal response
}
}
```
## 🔒 Security
- **Azure CLI Authentication**: Leverages your existing Azure device login
- **No Credential Storage**: Server doesn't store authentication tokens
- **Local Memory**: Schema cache stored locally, not transmitted
## 🐛 Troubleshooting
### Common Issues
1. **Authentication Errors**
```bash
# Re-authenticate with Azure CLI
az login --tenant your-tenant-id
```
2. **Memory Issues**
```bash
# Clear schema cache if corrupted (automatic backup created)
# Windows:
del "%APPDATA%\KQL_MCP\schema_memory.json"
# macOS/Linux:
rm ~/.local/share/KQL_MCP/schema_memory.json
```
3. **Connection Timeouts**
- Check cluster URI format
- Verify network connectivity
- Confirm Azure permissions
4. **Memory Path Issues**
- Server automatically creates fallback directory in `~/.kql_mcp_memory` if default path fails
- Check logs for memory path initialization messages
## 🤝 Contributing
We welcome contributions! Please do.
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/4R9UN/mcp-kql-server/issues)
- **PyPI Package**: [PyPI Project Page](https://pypi.org/project/mcp-kql-server/)
- **Author**: [Arjun Trivedi](mailto:arjuntrivedi42@yahoo.com)
- **Certified** : [MCPHub](https://mcphub.com/mcp-servers/4R9UN/mcp-kql-server)
## 🌟 Star History
[](https://star-history.com/#4R9UN/mcp-kql-server&Date)
---
**Happy Querying! 🎉**
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-kql-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, anthropic, azure, azure-data-explorer, claude, data-analytics, data-explorer, intelligent-caching, kql, kusto, mcp, model-context-protocol, query-execution, schema-memory",
"author": null,
"author_email": "Arjun Trivedi <arjuntrivedi42@yahoo.com>",
"download_url": "https://files.pythonhosted.org/packages/68/e6/1d7845563ce5e83dd848ad61a6af4e46234dc6958e011fdc71f65cd0a32a/mcp_kql_server-2.0.3.tar.gz",
"platform": null,
"description": "# MCP KQL Server\n[](https://mseep.ai/app/4r9un-mcp-kql-server)\n\n> **AI-Powered KQL Query Execution with Intelligent Schema Memory**\n\nA Model Context Protocol (MCP) server that provides intelligent KQL (Kusto Query Language) query execution with AI-powered schema caching and context assistance for Azure Data Explorer clusters.\n\n<!-- Badges Section -->\n[](https://mseep.ai/app/18772353-3d90-4b12-a253-cf752efaadd2)\n[](https://pypi.org/project/mcp-kql-server/)\n[](https://pypi.org/project/mcp-kql-server/)\n\n[](https://github.com/4R9UN/mcp-kql-server/actions)\n[](https://codecov.io/gh/4R9UN/mcp-kql-server)\n[](https://github.com/4R9UN/mcp-kql-server/security)\n[](https://github.com/4R9UN/mcp-kql-server)\n\n[](https://github.com/jlowin/fastmcp)\n[](https://azure.microsoft.com/en-us/services/data-explorer/)\n[](https://github.com/anthropics/mcp)\n[](https://github.com/4R9UN/mcp-kql-server/graphs/commit-activity)\n\n## \ud83d\ude80 Features\n\n- **\ud83c\udfaf Intelligent KQL Execution**: Execute KQL queries against any Azure Data Explorer cluster\n- **\ud83e\udde0 AI Schema Memory**: Automatic schema discovery and intelligent caching\n- **\ud83d\udcca Rich Visualizations**: Markdown table output with configurable formatting\n- **\u26a1 Performance Optimized**: Smart caching reduces cluster API calls\n- **\ud83d\udd10 Azure Authentication**: Seamless Azure CLI integration\n- **\ud83c\udfa8 Context-Aware**: AI-powered query assistance and error suggestions\n- **\ud83d\udd15 Clean Output**: Suppressed FastMCP branding for professional experience (v2.0.2+)\n\n## \ud83d\udcca MCP Tools Execution Flow\n\n### KQL Query Execution Flow\n\n```mermaid\ngraph TD\n A[\ud83d\udc64 User Submits KQL Query] --> B{\ud83d\udd0d Query Validation}\n B -->|\u274c Invalid| C[\ud83d\udcdd Syntax Error Response]\n B -->|\u2705 Valid| D[\ud83e\udde0 Load Schema Context]\n \n D --> E{\ud83d\udcbe Schema Cache Available?}\n E -->|\u2705 Yes| F[\u26a1 Load from Memory]\n E -->|\u274c No| G[\ud83d\udd0d Discover Schema]\n \n F --> H[\ud83c\udfaf Execute Query]\n G --> I[\ud83d\udcbe Cache Schema + AI Context]\n I --> H\n \n H --> J{\ud83c\udfaf Query Success?}\n J -->|\u274c Error| K[\ud83d\udea8 Enhanced Error Message]\n J -->|\u2705 Success| L[\ud83d\udcca Process Results]\n \n L --> M[\ud83c\udfa8 Generate Visualization]\n M --> N[\ud83d\udce4 Return Results + Context]\n \n K --> O[\ud83d\udca1 AI Suggestions]\n O --> N\n \n style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff\n style B fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff\n style C fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff\n style D fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff\n style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff\n style F fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff\n style G fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff\n style H fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff\n style I fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff\n style J fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff\n style K fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff\n style L fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff\n style M fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff\n style N fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff\n style O fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff\n```\n\n### Schema Memory Discovery Flow\n\n```mermaid\ngraph TD\n A[\ud83d\udc64 User Requests Schema Discovery] --> B[\ud83d\udd17 Connect to Cluster]\n B --> C[\ud83d\udcc2 Enumerate Databases]\n C --> D[\ud83d\udccb Discover Tables]\n \n D --> E[\ud83d\udd0d Get Table Schemas]\n E --> F[\ud83e\udd16 AI Analysis]\n F --> G[\ud83d\udcdd Generate Descriptions]\n \n G --> H[\ud83d\udcbe Store in Memory]\n H --> I[\ud83d\udcca Update Statistics]\n I --> J[\u2705 Return Summary]\n \n style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff\n style B fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff\n style C fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff\n style D fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff\n style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff\n style F fill:#e67e22,stroke:#bf6516,stroke-width:2px,color:#ffffff\n style G fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff\n style H fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff\n style I fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff\n style J fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff\n```\n\n\n## \ud83d\udccb Prerequisites\n\n- Python 3.10 or higher\n- Azure CLI installed and authenticated (`az login`)\n- Access to Azure Data Explorer cluster(s)\n\n## \ud83d\ude80 One-Command Installation\n\n### Quick Install (Recommended)\n\n#### From Source\n\n```bash\ngit clone https://github.com/4R9UN/mcp-kql-server.git && cd mcp-kql-server && pip install -e .\n```\n### Alternative Installation Methods\n\n```bash\npip install mcp-kql-server\n```\n\n**That's it!** The server automatically:\n- \u2705 Sets up memory directories in `%APPDATA%\\KQL_MCP` (Windows) or `~/.local/share/KQL_MCP` (Linux/Mac)\n- \u2705 Configures optimal defaults for production use\n- \u2705 Suppresses verbose Azure SDK logs\n- \u2705 No environment variables required\n\n\n## \ud83d\udcf1 MCP Client Configuration\n\n### Claude Desktop\n\nAdd to your Claude Desktop MCP settings file (`mcp_settings.json`):\n\n**Location:**\n- **Windows**: `%APPDATA%\\Claude\\mcp_settings.json`\n- **macOS**: `~/Library/Application Support/Claude/mcp_settings.json`\n- **Linux**: `~/.config/Claude/mcp_settings.json`\n\n```json\n{\n \"mcpServers\": {\n \"mcp-kql-server\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_kql_server\"],\n \"env\": {}\n }\n }\n}\n```\n\n### VSCode (with MCP Extension)\n\nAdd to your VSCode MCP configuration:\n\n**Settings.json location:**\n- **Windows**: `%APPDATA%\\Code\\User\\settings.json`\n- **macOS**: `~/Library/Application Support/Code/User/settings.json`\n- **Linux**: `~/.config/Code/User/settings.json`\n\n```json\n{\n \"mcp.servers\": {\n \"mcp-kql-server\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_kql_server\"],\n \"cwd\": null,\n \"env\": {}\n }\n }\n}\n```\n\n### Roo-code (Cline Extension)\n\nAdd to your Roo-code MCP settings:\n\n**MCP Settings location:**\n- **All platforms**: Through Roo-code extension settings or `mcp_settings.json`\n\n```json\n{\n \"mcpServers\": {\n \"kql-server\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_kql_server\"],\n \"env\": {},\n \"description\": \"KQL Server for Azure Data Explorer queries with AI assistance\"\n }\n }\n}\n```\n\n### Generic MCP Client\n\nFor any MCP-compatible application:\n\n```bash\n# Command to run the server\npython -m mcp_kql_server\n\n# Server provides these tools:\n# - kql_execute: Execute KQL queries with AI context\n# - kql_schema_memory: Discover and cache cluster schemas\n```\n\n### Configuration with Environment Variables\n\nYou can customize the server behavior with environment variables:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-kql-server\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_kql_server\"],\n \"env\": {\n \n }\n }\n }\n}\n```\n## \ud83d\udd27 Quick Start\n\n### 1. Authenticate with Azure (One-time setup)\n\n```bash\naz login\n```\n\n### 2. Start the MCP Server (Zero configuration)\n\n```bash\npython -m mcp_kql_server\n```\n\nThe server starts immediately with:\n- \ud83d\udcc1 **Auto-created memory path**: `%APPDATA%\\KQL_MCP\\cluster_memory`\n- \ud83d\udd27 **Optimized defaults**: No configuration files needed\n- \ud83d\udd10 **Secure setup**: Uses your existing Azure CLI credentials\n\n### 3. Use via MCP Client\n\nThe server provides two main tools:\n\n> #### `kql_execute` - Execute KQL Queries with AI Context\n> #### `kql_schema_memory` - Discover and Cache Cluster Schemas\n\n\n## \ud83d\udca1 Usage Examples\n\n### Basic Query Execution\n\nAsk your MCP client (like Claude):\n> \"Execute this KQL query against the help cluster: `cluster('help.kusto.windows.net').database('Samples').StormEvents | take 10` and summarize the result and give me high level insights \"\n\n### Complex Analytics Query\n\nAsk your MCP client:\n> \"Query the Samples database in the help cluster to show me the top 10 states by storm event count, include visualization\"\n\n### Schema Discovery\n\nAsk your MCP client:\n> \"Discover and cache the schema for the help.kusto.windows.net cluster, then tell me what databases and tables are available\"\n\n### Data Exploration with Context\n\nAsk your MCP client:\n> \"Using the StormEvents table in the Samples database on help cluster, show me all tornado events from 2007 with damage estimates over $1M\"\n\n### Time-based Analysis\n\nAsk your MCP client:\n> \"Analyze storm events by month for the year 2007 in the StormEvents table, group by event type and show as a visualization\"\n\n\n\n## \ud83c\udfaf Key Benefits\n\n### For Data Analysts\n- **\u26a1 Faster Query Development**: AI-powered autocomplete and suggestions\n- **\ud83c\udfa8 Rich Visualizations**: Instant markdown tables for data exploration\n- **\ud83e\udde0 Context Awareness**: Understand your data structure without documentation\n\n### For DevOps Teams\n- **\ud83d\udd04 Automated Schema Discovery**: Keep schema information up-to-date\n- **\ud83d\udcbe Smart Caching**: Reduce API calls and improve performance\n- **\ud83d\udd10 Secure Authentication**: Leverage existing Azure CLI credentials\n\n### For AI Applications\n- **\ud83e\udd16 Intelligent Query Assistance**: AI-generated table descriptions and suggestions\n- **\ud83d\udcca Structured Data Access**: Clean, typed responses for downstream processing\n- **\ud83c\udfaf Context-Aware Responses**: Rich metadata for better AI decision making\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```mermaid\ngraph TD\n A[MCP Client<br/>Claude/AI/Custom] <--> B[MCP KQL Server<br/>FastMCP Framework]\n B <--> C[Azure Data Explorer<br/>Kusto Clusters]\n B <--> D[Schema Memory<br/>Local AI Cache]\n \n style A fill:#4a90e2,stroke:#2c5282,stroke-width:3px,color:#ffffff\n style B fill:#8e44ad,stroke:#6a1b99,stroke-width:3px,color:#ffffff\n style C fill:#e67e22,stroke:#bf6516,stroke-width:3px,color:#ffffff\n style D fill:#27ae60,stroke:#1e8449,stroke-width:3px,color:#ffffff\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\nmcp-kql-server/\n\u251c\u2500\u2500 mcp_kql_server/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 mcp_server.py # Main MCP server implementation\n\u2502 \u251c\u2500\u2500 execute_kql.py # KQL query execution logic\n\u2502 \u251c\u2500\u2500 schema_memory.py # Schema caching and discovery\n\u2502 \u251c\u2500\u2500 unified_memory.py # Advanced memory management\n\u2502 \u251c\u2500\u2500 kql_auth.py # Azure authentication\n\u2502 \u251c\u2500\u2500 utils.py # Utility functions\n\u2502 \u2514\u2500\u2500 constants.py # Configuration constants\n\u251c\u2500\u2500 docs/ # Documentation\n\u251c\u2500\u2500 Example/ # Usage examples\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md # This file\n```\n\n## \ud83d\ude80 Advanced Usage\n\n### Custom Memory Path\n\n```python\n{\n \"tool\": \"kql_execute\",\n \"input\": {\n \"query\": \"...\",\n \"cluster_memory_path\": \"/custom/memory/path\"\n }\n}\n```\n\n### Force Schema Refresh\n\n```python\n{\n \"tool\": \"kql_schema_memory\",\n \"input\": {\n \"cluster_uri\": \"mycluster\",\n \"force_refresh\": true\n }\n}\n```\n\n### Performance Optimization\n\n```python\n{\n \"tool\": \"kql_execute\",\n \"input\": {\n \"query\": \"...\",\n \"use_schema_context\": false, # Disable for faster execution\n \"visualize\": false # Disable for minimal response\n }\n}\n```\n\n## \ud83d\udd12 Security\n\n- **Azure CLI Authentication**: Leverages your existing Azure device login\n- **No Credential Storage**: Server doesn't store authentication tokens\n- **Local Memory**: Schema cache stored locally, not transmitted\n\n## \ud83d\udc1b Troubleshooting\n\n### Common Issues\n\n1. **Authentication Errors**\n ```bash\n # Re-authenticate with Azure CLI\n az login --tenant your-tenant-id\n ```\n\n2. **Memory Issues**\n ```bash\n # Clear schema cache if corrupted (automatic backup created)\n # Windows:\n del \"%APPDATA%\\KQL_MCP\\schema_memory.json\"\n \n # macOS/Linux:\n rm ~/.local/share/KQL_MCP/schema_memory.json\n ```\n\n3. **Connection Timeouts**\n - Check cluster URI format\n - Verify network connectivity\n - Confirm Azure permissions\n\n4. **Memory Path Issues**\n - Server automatically creates fallback directory in `~/.kql_mcp_memory` if default path fails\n - Check logs for memory path initialization messages\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please do. \n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/4R9UN/mcp-kql-server/issues)\n- **PyPI Package**: [PyPI Project Page](https://pypi.org/project/mcp-kql-server/)\n- **Author**: [Arjun Trivedi](mailto:arjuntrivedi42@yahoo.com)\n- **Certified** : [MCPHub](https://mcphub.com/mcp-servers/4R9UN/mcp-kql-server)\n\n## \ud83c\udf1f Star History\n\n[](https://star-history.com/#4R9UN/mcp-kql-server&Date)\n\n---\n\n**Happy Querying! \ud83c\udf89**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-Powered MCP server for KQL query execution with intelligent schema memory and context assistance",
"version": "2.0.3",
"project_urls": {
"Changelog": "https://github.com/4R9UN/mcp-kql-server/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/4R9UN/mcp-kql-server",
"Issues": "https://github.com/4R9UN/mcp-kql-server/issues",
"Repository": "https://github.com/4R9UN/mcp-kql-server.git"
},
"split_keywords": [
"ai",
" anthropic",
" azure",
" azure-data-explorer",
" claude",
" data-analytics",
" data-explorer",
" intelligent-caching",
" kql",
" kusto",
" mcp",
" model-context-protocol",
" query-execution",
" schema-memory"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5a1e63d7ad622cc82bbc1bf4edf06f1df95d81d629e027d5597de12a5f3024de",
"md5": "ca5182151393fdf6dcef137f21ffb993",
"sha256": "f1b3b92a75debe84941fffc21abd936247dfaf970d622d023fc5fee94b41ac29"
},
"downloads": -1,
"filename": "mcp_kql_server-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca5182151393fdf6dcef137f21ffb993",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 37149,
"upload_time": "2025-08-08T07:19:05",
"upload_time_iso_8601": "2025-08-08T07:19:05.065660Z",
"url": "https://files.pythonhosted.org/packages/5a/1e/63d7ad622cc82bbc1bf4edf06f1df95d81d629e027d5597de12a5f3024de/mcp_kql_server-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "68e61d7845563ce5e83dd848ad61a6af4e46234dc6958e011fdc71f65cd0a32a",
"md5": "672d5b1d47ca669a407802b6d24e5e5d",
"sha256": "b854ac484efdeeb2677188b93f34c0e1e5b5e92a1decb3dcbc222bd7b246843c"
},
"downloads": -1,
"filename": "mcp_kql_server-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "672d5b1d47ca669a407802b6d24e5e5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 347399,
"upload_time": "2025-08-08T07:19:06",
"upload_time_iso_8601": "2025-08-08T07:19:06.282811Z",
"url": "https://files.pythonhosted.org/packages/68/e6/1d7845563ce5e83dd848ad61a6af4e46234dc6958e011fdc71f65cd0a32a/mcp_kql_server-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 07:19:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "4R9UN",
"github_project": "mcp-kql-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "tabulate",
"specs": [
[
">=",
"0.9.0"
]
]
}
],
"lcname": "mcp-kql-server"
}
JSON
