KQL MCP Server

A Model Context Protocol (MCP) server that searches all of GitHub for KQL (Kusto Query Language) queries using natural language, with built-in schema intelligence for 331+ KQL tables from Microsoft Defender XDR, Microsoft Sentinel, and Azure Monitor.

Features

ASIM Schema Validation & Normalization

• Advanced Security Information Model (ASIM) Support: Work with 11 GA ASIM schemas for normalized security event queries
• Comprehensive Field Validation: 230+ fields across all ASIM schemas with detailed metadata
• Schema Information: Get detailed information about ASIM schemas including:
  • Key fields and entities for each schema
  • Field classifications (Mandatory, Recommended, Optional, Conditional)
  • Field descriptions, types, and examples
  • Entity relationships between schemas
• Query Templates: Generate ready-to-use KQL query templates for any ASIM schema
• Parser Recommendations: Get naming conventions and best practices for ASIM parsers
• Supported Schemas: Alert Event, Authentication Event, Network Session, Process Event, File Activity, DNS Activity, Audit Event, Registry Event, DHCP Activity, User Management, and Web Session

GitHub Search & Query Discovery

• Universal GitHub Search: Search across ALL public GitHub repositories for KQL queries
• Natural Language Interface: Use plain English to describe what you're looking for
  • "Find security threat hunting queries"
  • "Show me Microsoft Sentinel detection rules for failed logins"
  • "Get queries for monitoring Kubernetes events"
• Intelligent Parsing: Automatically extracts and parses KQL queries from source files
• Smart Ranking: Results ranked by relevance, repository popularity, and query quality
• Context Aware: Includes surrounding documentation and comments for better understanding
• Flexible Search: Search by file, repository, or natural language query
• Pagination Support: Fetch up to 1000 results with automatic pagination

KQL Table Schema Intelligence & Query Generation

• Comprehensive Schema Index: 331+ tables from Microsoft Defender XDR, Microsoft Sentinel, and Azure Monitor Logs
• Validated Query Generation: Generate KQL queries with full schema validation
  • Table names verified against schema index
  • Column names and data types validated
  • Syntax correctness guaranteed
  • Returns validation results with errors/warnings
• Query Validation: Validate existing queries for correctness before execution
• Natural Language Table Search: Find tables by describing what data you need - "authentication events", "email security", "vulnerability data"
• Detailed Schema Information: Complete column definitions with data types, descriptions, and usage examples
• Smart Query Templates: Generate KQL query templates automatically from table schemas
• Documentation Links: Automatic Microsoft Learn documentation links for tables and operators
• Column Discovery: Find which tables contain specific columns
• Join Suggestions: Discover common join patterns between related tables
• Browse by Category: Explore tables organized by function (57 categories)
• GitHub Examples Fallback: Search GitHub for examples when tables aren't in schema index

Performance & Management

• Smart Caching: LRU cache reduces API calls and improves performance
• Rate Limit Management: Built-in GitHub API rate limit tracking and warnings

Installation

Prerequisites

• A GitHub Classic Personal Access Token with public_repo scope
• An MCP-compatible client (see supported clients below)

Supported MCP Clients

This server works with any MCP-compatible client, including:

• Claude Desktop - Anthropic's official desktop app
• ChatGPT - OpenAI's ChatGPT with MCP support (Pro, Plus, Team, Business, Enterprise, Education accounts)
• GitHub Copilot - VS Code, JetBrains, Eclipse, and Xcode (requires GitHub Copilot subscription)
• Google Gemini CLI - Google's open-source AI agent with native MCP support
• Zed Editor - High-performance code editor with built-in MCP support
• Cody - Sourcegraph's AI coding assistant
• Replit - Cloud-based development environment

Setup for Claude Desktop

No installation required! Use npx to run the package directly from NPM.

Configure Claude Desktop:

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "kql-search": {
      "command": "npx",
      "args": ["-y", "kql-search-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "FAVORITE_REPOS":
          "Azure/Azure-Sentinel,microsoft/Microsoft-365-Defender-Hunting-Queries"
      }
    }
  }
}

Optional: Add FAVORITE_REPOS to quickly search your most-used repositories (comma-separated list of owner/repo)

Get a GitHub Token:

• Go to https://github.com/settings/tokens/new
• Give it a descriptive name: "KQL MCP Server"
• Under "Select scopes", check public_repo
• Click "Generate token" and copy it immediately
• Replace your_github_token_here with your token

Restart Claude Desktop and you're ready to go!

Note: The -y flag tells npx to automatically use the package without prompting. This ensures the MCP server starts correctly.

Setup for ChatGPT

Requirements: ChatGPT Pro, Plus, Team, Business, Enterprise, or Education account

1. Open ChatGPT and go to Settings
2. Navigate to Connectors → Advanced → Developer Mode
3. Add a new MCP server with:
   • Name: KQL Search
   • Command: npx
   • Args: -y kql-search-mcp
   • Environment Variables:
     • GITHUB_TOKEN: your_github_token_here
     • FAVORITE_REPOS: Azure/Azure-Sentinel,microsoft/Microsoft-365-Defender- Hunting-Queries (optional)

Note: MCP support in ChatGPT is available via Developer Mode and requires a paid subscription.

Setup for VS Code Extension (GitHub Copilot)

Requirements: VS Code 1.107+ with GitHub Copilot (any model)

⚠️ IMPORTANT: The VS Code extension does NOT require Node.js or npx. It comes bundled with the MCP server.

Installation:

1. Install the extension from VS Code Marketplace:

   • Search for "KQL Search MCP" in the Extensions panel
   • Or install directly: kql-search-mcp

2. Set your GitHub token using Command Palette:

   KQL Search MCP: Set GitHub Token

3. (Optional) Configure favorite repositories:

   KQL Search MCP: Set Favorite Repositories

Works with any GitHub Copilot model, including:

• Claude Opus 4.5 Preview
• GPT-4o
• o1-preview
• o1-mini
• Any other GitHub Copilot supported model

Verification:

• Run KQL Search MCP: Check Extension Status from Command Palette
• The extension should show as active with your token set

Setup for GitHub Copilot (MCP Configuration File)

Requirements: GitHub Copilot subscription and VS Code 1.102+

⚠️ NOTE: This is an alternative setup using .vscode/mcp.json configuration. The VS Code extension above is easier and doesn't require npx.

1. Ensure MCP support is enabled in your organization (Enterprise/Team admins must enable the "MCP servers in Copilot" policy)
2. Create or edit .vscode/mcp.json in your project root:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "github-token",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "kql-search": {
      "command": "npx",
      "args": ["-y", "kql-search-mcp"],
      "env": {
        "GITHUB_TOKEN": "${input:github-token}",
        "FAVORITE_REPOS":
          "Azure/Azure-Sentinel,microsoft/Microsoft-365-Defender-Hunting-Queries"
      }
    }
  }
}

1. VS Code will prompt you for your GitHub token when the server starts
2. Click "Start" in the MCP configuration file to initialize the server

Note: For JetBrains, Eclipse, or Xcode, consult the GitHub Copilot MCP documentation.

Setup for Google Gemini CLI

Requirements: Gemini CLI installed

1. Install Gemini CLI:

   npm install -g @google/gemini-cli

2. Configure the MCP server:

   export GITHUB_TOKEN="your_github_token_here"
   export FAVORITE_REPOS="Azure/Azure-Sentinel,microsoft/Microsoft-365-Defender-Hunting-Queries"
   gemini-cli --mcp-server "npx -y kql-search-mcp"

Note: Gemini CLI has native MCP support and can connect to any MCP server using the --mcp-server flag.

Setup for Other MCP Clients

For Zed, Cody, Replit, or other MCP-compatible clients, refer to their specific MCP configuration documentation. The general configuration pattern is:

• Command: npx
• Args: -y kql-search-mcp
• Environment Variables:
  • GITHUB_TOKEN: your GitHub personal access token
  • FAVORITE_REPOS: comma-separated list of repositories (optional)

Enhanced Documentation with Microsoft Docs MCP (Recommended)

For the best experience generating and validating KQL queries, we strongly recommend installing the Microsoft Docs MCP server alongside this KQL MCP server.

Recommended Configuration

✅ KQL-Search-MCP: Install via NPX (no installation needed, runs directly from npm) ✅ Microsoft Docs MCP: Install via Docker MCP Gateway (requires Docker Desktop)

This combination gives you:

• 100% validated KQL queries with our schema intelligence
• Real-time access to official Microsoft Learn documentation
• Best of both worlds: local schema validation + cloud-hosted docs

What is Microsoft Docs MCP?

The Microsoft Docs MCP is an official , open-source, cloud-hosted service from Microsoft that provides real-time access to Microsoft Learn documentation through the Model Context Protocol.

Benefits of Using Both Servers Together

| Feature | KQL MCP Server (This Server) | Microsoft Docs MCP | Combined | |---------|------------------------------|-------------------|----------| | Query Generation | ✅ 100% validated against 331+ table schemas | ❌ No schema knowledge | ✅ Validated queries + official docs | | Schema Information | ✅ Structured table/column data | ❌ No structured schemas | ✅ Best of both | | Latest Documentation | ✅ Automated weekly schema checks | ✅ Always current from MS Learn | ✅ Verified with latest docs | | Query Examples | ✅ GitHub search across all repos | ✅ Official Microsoft examples | ✅ Maximum coverage | | Operator Documentation | ✅ Documentation links | ✅ Full operator details | ✅ Complete reference |

How to Install Microsoft Docs MCP

The Microsoft Docs MCP is a cloud-hosted service that requires Docker MCP Gateway to access. Add it to your existing configuration:

Prerequisites:

• Docker Desktop installed and running
• MCP Gateway (included with Docker Desktop)

For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kql-search": {
      "command": "npx",
      "args": ["-y", "kql-search-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "FAVORITE_REPOS": "Azure/Azure-Sentinel,microsoft/Microsoft-365-Defender-Hunting-Queries"
      }
    },
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

For GitHub Copilot (.vscode/mcp.json):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "github-token",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "kql-search": {
      "command": "npx",
      "args": ["-y", "kql-search-mcp"],
      "env": {
        "GITHUB_TOKEN": "${input:github-token}",
        "FAVORITE_REPOS": "Azure/Azure-Sentinel,microsoft/Microsoft-365-Defender-Hunting-Queries"
      }
    },
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

Microsoft Docs MCP Tools

When installed, you'll have access to these additional tools:

1. microsoft_docs_search - Semantic search across Microsoft Learn documentation
2. microsoft_docs_fetch - Retrieve specific documentation pages in markdown format
3. microsoft_code_sample_search - Find official Microsoft/Azure code samples

How They Work Together

User: "Generate a query for risky sign-ins"
  ↓
KQL MCP: Generates validated query using IdentityProtection schema
  ↓
Microsoft Docs MCP: Provides latest Identity Protection documentation
  ↓
Result: Validated query + official documentation + best practices

Check Installation Status

Use the check_microsoft_docs_mcp tool to get detailed installation instructions and verify your setup.

More Information

• Repository: https://github.com/MicrosoftDocs/mcp
• Microsoft MCP Catalog: https://github.com/microsoft/mcp
• No API Key Required: Free and maintained by Microsoft
• Cloud-Hosted: No local installation needed

Usage

Once configured, the KQL MCP server provides 34 tools in your MCP client:

ASIM Schema Tools (13 tools)

Work with ASIM (Advanced Security Information Model) schemas for normalized security events:

1. search_asim_schemas - Search for ASIM schemas by keyword
2. get_asim_schema_info - Get detailed information about a specific ASIM schema
3. get_asim_field_info - Get information about a specific ASIM field
4. generate_asim_query_template - Generate KQL query templates for ASIM schemas
5. get_asim_parser_recommendations - Get parser naming conventions and best practices
6. list_asim_schemas - List all available ASIM schemas
7. search_asim_fields - Search for fields across ASIM schemas
8. validate_asim_parser - Validate parser implementation against schema requirements
9. get_asim_parser_requirements - Get mandatory and recommended fields for a schema
10. compare_parser_to_schema - Compare parser fields against schema requirements
11. get_asim_logical_types - Get ASIM logical types reference
12. get_asim_schema_relationships - Get relationships between ASIM schemas
13. list_available_asim_schemas - List all ASIM schemas for validation

ASIM Schema Tools Details

1. Search ASIM Schemas (search_asim_schemas)

Search for ASIM (Advanced Security Information Model) schemas by keyword:

Examples:

Find ASIM schemas for authentication

Search for network ASIM schema

Show me file activity ASIM schema

Find DNS event schema

Parameters:

• query (required): Keyword to search (e.g., "authentication", "network", "file", "process", "dns")

Returns:

• Schema names and versions
• Status (GA, Preview)
• Descriptions and key fields
• List of entities in each schema

2. Get ASIM Schema Info (get_asim_schema_info)

Get comprehensive information about a specific ASIM schema:

Examples:

Get information about the authentication event schema

Show me details for network session schema

What fields are in the alert event schema?

Get schema information for DNS activity

Parameters:

• schemaName (required): ASIM schema name (e.g., "authentication_event", "network_session")

Returns:

• All fields in the schema with classifications
• Field types and logical types
• Entity information
• Key fields required for the schema
• Field relationships and dependencies
• Common use cases

3. Get ASIM Field Info (get_asim_field_info)

Get detailed information about a specific ASIM field:

Examples:

Get information about the EventStartTime field

Show me details for the UserName field

What is the EventResult field used for?

Get details on the SourceIPAddress field

Parameters:

• fieldName (required): ASIM field name (e.g., "EventStartTime", "UserName", "EventResult")

Returns:

• Field type and logical type
• Field class (Mandatory, Recommended, Optional)
• Description and purpose
• Example values
• Allowed values (where applicable)
• Related fields in other schemas

4. Generate ASIM Query Template (generate_asim_query_template)

Generate a ready-to-use KQL query template for an ASIM schema:

Examples:

Generate a query template for the authentication event schema

Create a template for network session queries

Generate a query starting point for file activity

Give me a template for DNS activity queries

Parameters:

• schemaName (required): ASIM schema name

Returns:

• Complete KQL query template
• Standard filter examples
• Common field selections
• Best practices for the schema
• Query explanation

5. Get ASIM Parser Recommendations (get_asim_parser_recommendations)

Get naming conventions and best practices for creating ASIM parsers:

Examples:

Get parser recommendations for authentication events

Show me naming conventions for network session parsers

What are the best practices for creating ASIM parsers?

Get recommendations for DNS activity parsers

Parameters:

• schemaName (required): ASIM schema name

Returns:

• Unifying parser naming conventions
• Source-specific parser naming patterns
• Parser recommendations
• Query template examples
• Documentation links

6. List ASIM Schemas (list_asim_schemas)

List all available ASIM schemas with versions and status:

Examples:

List all available ASIM schemas

Show me all ASIM schemas

What ASIM schemas are available?

List ASIM schema catalog

Returns:

• All 11 ASIM schemas with current versions
• Status for each schema (GA, Preview)
• Schema descriptions
• Key entities and fields
• Supported data sources

7. Search ASIM Fields (search_asim_fields)

Search for fields across all ASIM schemas:

Examples:

Find all ASIM fields related to user accounts

Search for timestamp fields in ASIM

Find fields related to IP addresses

Search for process-related fields

Parameters:

• query (required): Search term for fields

Returns:

• Matching fields across all schemas
• Field names and types
• Schemas containing each field
• Field descriptions
• Usage examples

8. Validate ASIM Parser (validate_asim_parser)

Validate an ASIM parser implementation against schema requirements:

Examples:

Validate parser with fields: EventStartTime, EventEndTime, EventType, EventResult for authentication_event schema

Check if my parser has all mandatory fields for network_session

Parameters:

• schemaName (required): ASIM schema name (e.g., "authentication_event", "network_session")
• parserName (required): Name of the parser being validated
• parserFields (required): List of field names provided by the parser

Returns:

• Validation status (passed/issues found)
• Missing mandatory fields (if any)
• Missing recommended fields (if any)
• Extra/unrecognized fields (if any)
• Coverage summary

9. Get ASIM Parser Requirements (get_asim_parser_requirements)

Get mandatory and recommended fields required for an ASIM parser:

Examples:

What fields are required for an authentication event parser?

Show me mandatory and recommended fields for network session

Parameters:

• schemaName (required): ASIM schema name

Returns:

• List of all mandatory fields with descriptions
• List of all recommended fields with descriptions
• Total field count for the schema

10. Compare Parser to Schema (compare_parser_to_schema)

Compare parser fields against schema requirements and identify gaps:

Examples:

Compare my parser fields against the authentication_event schema

Show field coverage for my network session parser

Parameters:

• schemaName (required): ASIM schema name
• parserFields (required): List of fields in the parser

Returns:

• Field coverage percentage
• Matched and unmatched fields
• Fields missing from parser (organized by requirement level)
• Detailed gap analysis

11. Get ASIM Logical Types (get_asim_logical_types)

Get reference information about ASIM logical types:

Examples:

What are the ASIM logical types?

Show me logical type definitions and examples

Returns:

• All logical types used in ASIM
• Description for each type
• Examples for each logical type
• Formatting requirements

12. Get ASIM Schema Relationships (get_asim_schema_relationships)

Get relationships between ASIM schemas:

Examples:

What schemas are related to authentication events?

Show me how network session relates to other schemas

Parameters:

• schemaName (required): ASIM schema name

Returns:

• Related schemas
• Relationship descriptions
• Cross-schema field mappings

13. List Available ASIM Schemas (list_available_asim_schemas)

List all available ASIM schemas for validation and normalization:

Examples:

List all ASIM schemas available for validation

Show me all ASIM schemas with field counts

Returns:

• Complete list of all ASIM schemas
• Schema versions and status
• Description for each schema
• Field count for each schema

Search for KQL queries across GitHub repositories:

1. search_kql_queries - Search all of GitHub for KQL queries using natural language
2. get_kql_from_file - Extract queries from a specific file
3. search_kql_repositories - Find repositories containing KQL queries
4. get_rate_limit - View GitHub API rate limit status
5. search_repo_kql_queries - Search within a specific repository
6. search_user_kql_queries - Search all repos from a user/org
7. search_favorite_repos - Search your configured favorite repos
8. get_cache_stats - View cache performance and stats

1. Search KQL Queries (search_kql_queries)

Search all of GitHub for KQL queries using natural language:

Examples:

Find KQL queries for detecting failed login attempts

Show me Microsoft Sentinel queries for threat hunting

Get queries for monitoring Entra ID sign-ins

Search for queries that detect lateral movement in Active Directory

Find PowerShell execution detection queries

Parameters:

• query (required): Natural language description of what you're looking for
• max_results (optional): Maximum number of queries to return (default: 5, max: 50)
• include_context (optional): Include surrounding documentation (default: true)
• sort_by (optional): Sort by 'relevance', 'stars', or 'updated' (default: relevance)

Returns:

• KQL queries with syntax highlighting
• Repository and file information
• Descriptions and context
• Relevance scores
• Source code links

2. Get KQL from File (get_kql_from_file)

Extract all KQL queries from a specific file:

Examples:

Get KQL queries from Azure/Azure-Sentinel file Solutions/Azure%20Activity/Hunting%20Queries/Granting_Permissions_to_Account.yaml

Extract queries from microsoft/Microsoft-365-Defender-Hunting-Queries file Persistence/scheduled%20task%20creation.txt

Show me the queries in reprise99/Sentinel-Queries file Azure%20Active%20Directory/Identity-RiskySigninFollowedbyAdminMFAChange.kql

Get queries from Azure/Azure-Sentinel file Detections/SigninLogs/PrivilegedAccountsSignInFailureSpikes.yaml

Extract KQL from microsoft/Microsoft-365-Defender-Hunting-Queries file Exfiltration/EmailAccessViaActiveSync.txt

Parameters:

• owner (required): Repository owner (username or organization)
• repo (required): Repository name
• path (required): File path within the repository
• include_context (optional): Include surrounding documentation (default: true)

Returns:

• All KQL queries extracted from the file
• Query descriptions and comments
• Context from surrounding code
• File metadata

3. Search KQL Repositories (search_kql_repositories)

Find GitHub repositories that contain KQL queries:

Examples:

Search for repositories with Microsoft Sentinel detection rules

Find repositories containing Microsoft Defender hunting queries

Show me repos with Kubernetes monitoring KQL queries

Find repositories with threat hunting KQL examples

Search for Azure Monitor log analytics query collections

Parameters:

• query (required): Search terms to find relevant repositories

Returns:

• Repository names and descriptions
• Star counts and activity metrics
• Repository URLs
• Primary programming languages

4. Check Rate Limit (get_rate_limit)

View current GitHub API rate limit status:

Examples:

Check GitHub API rate limit status

How many API requests do I have remaining?

Show rate limit info

What's my current rate limit?

Check API quota remaining

Returns:

• Current rate limit (requests per hour)
• Remaining requests
• Reset time
• Used requests count

5. Search Specific Repository (search_repo_kql_queries)

Search for KQL queries within a specific GitHub repository:

Examples:

Find authentication queries in Azure/Azure-Sentinel

Search for network monitoring in microsoft/Microsoft-365-Defender-Hunting-Queries

Get queries for failed login attempts in Azure/Azure-Sentinel

Find email phishing detection in microsoft/Microsoft-365-Defender-Hunting-Queries

Search reprise99/Sentinel-Queries for brute force queries

Find ransomware detection in Azure/Azure-Sentinel

Parameters:

• owner (required): Repository owner (e.g., "Azure", "microsoft")
• repo (required): Repository name (e.g., "Azure-Sentinel")
• query (required): Natural language description
• max_results (optional): Maximum results (default: 5, max: 50)
• include_context (optional): Include documentation (default: true)

Returns:

• KQL queries from the specified repository
• File paths and locations
• Query descriptions
• Relevance scores

6. Search User/Organization Repositories (search_user_kql_queries)

Search all repositories owned by a specific GitHub user or organization:

Examples:

Find all threat hunting queries from microsoft

Search Azure organization for detection rules

Get all KQL queries from reprise99's repositories

Find DNS queries across all Azure repositories

Search microsoft for PowerShell hunting queries

Find all malware detection queries from Azure

Parameters:

• user (required): GitHub username or org (e.g., "microsoft", "Azure")
• query (required): Natural language description
• max_results (optional): Maximum results (default: 5, max: 50)
• include_context (optional): Include documentation (default: true)
• sort_by (optional): Sort by 'relevance', 'stars', or 'updated'

Returns:

• KQL queries from all user/org repositories
• Repository names for each query
• File locations
• Context and descriptions

7. Search Favorite Repositories (search_favorite_repos)

Search only your configured favorite repositories:

Examples:

Find failed login queries in my favorite repos

Search my favorites for lateral movement detection

Get phishing email queries from favorite repositories

Find all process execution queries in favorites

Search favorites for suspicious registry modifications

Parameters:

• query (required): Natural language description
• max_results (optional): Maximum results (default: 5, max: 50)
• include_context (optional): Include documentation (default: true)

Configuration: Set FAVORITE_REPOS environment variable in your MCP config (see Installation section above)

Returns:

• KQL queries from your favorite repositories
• Repository names
• File paths
• Query context

8. Get Cache Statistics (get_cache_stats)

View cache performance and optionally clear cached results:

Examples:

Show me cache statistics

What's my cache hit rate?

Get cache stats

Clear the query cache

Show cache stats and clear it

How many cached queries do I have?

Parameters:

• clear_cache (optional): Clear the cache after showing stats (default: false)

Returns:

• Search cache size
• File cache size
• Cache hit rates
• TTL information

Cache Benefits:

• Reduces GitHub API calls for repeated searches
• 30-minute TTL for search results
• 60-minute TTL for file contents
• Automatic LRU eviction for optimal memory usage

Schema Intelligence Tools (8 tools)

Discover and work with KQL table schemas, plus generate and validate queries:

1. get_table_schema - Get comprehensive schema information for a specific table
2. search_tables - Search for tables using natural language
3. list_table_categories - Browse all available table categories
4. get_tables_by_category - Get all tables in a specific category
5. generate_query_template - Generate a ready-to-use KQL query template
6. generate_query_from_natural_language - Create complete queries from descriptions
7. find_column - Find which tables contain a specific column
8. get_schema_statistics - View schema index statistics and coverage

1. Get Table Schema (get_table_schema)

Get comprehensive schema information for a specific KQL table:

Examples:

Get schema for SigninLogs table

Show me the DeviceProcessEvents table schema

What columns are in the SecurityAlert table?

Give me schema details for ASimFileEventLogs

Show me the EmailEvents table structure

Parameters:

• table_name (required): Name of the KQL table (e.g., "SigninLogs", "DeviceProcessEvents")

Returns:

• Complete schema including all columns with data types
• Column descriptions and common column indicators
• Join suggestions for related tables
• Example queries

Supported Tables: 331+ tables from Microsoft Defender XDR, Microsoft Sentinel , and Azure Monitor Logs.

2. Search Tables (search_tables)

Search for KQL tables using natural language:

Examples:

Find tables for authentication events

Show me email security tables

Search for tables with vulnerability data

Which tables contain file activity information?

Find tables related to network traffic monitoring

Parameters:

• query (required): Natural language description of the type of table you need
• max_results (optional): Maximum number of tables to return (default: 10)

Returns:

• Ranked list of tables with relevance scores
• Table descriptions
• Common columns for each table

3. List Table Categories (list_table_categories)

Browse all available table categories:

Examples:

List all table categories

Show me available KQL table categories

What categories of tables are available?

Browse all table types

Show me how tables are organized

Returns:

• Complete list of 57 categories
• Categories include Authentication & Identity, Security & Threats , Email & Collaboration, Network Activity, and more

4. Get Tables by Category (get_tables_by_category)

Get all tables in a specific category:

Examples:

Show me all Authentication & Identity tables

List tables in the Security & Threats category

Get all Email & Collaboration tables

Show me tables in the Network Activity category

List all Device & Endpoint tables

Parameters:

• category (required): Category name (use list_table_categories to see available categories)

Returns:

• All tables in the specified category
• Table descriptions
• Common columns for each table

5. Generate Query Template (generate_query_template)

Generate a ready-to-use KQL query template for a specific table:

Examples:

Generate a query template for SigninLogs

Create a template query for DeviceProcessEvents

Give me a starting query for SecurityAlert table

Build a basic query for EmailEvents

Generate template for ASimFileEventLogs

Parameters:

• table_name (required): Name of the KQL table
• include_comments (optional): Include explanatory comments (default: true)

Returns:

• Ready-to-use KQL query template
• Common filters and time ranges
• Standard column selections
• Optional explanatory comments

6. Generate Query from Natural Language (generate_query_from_natural_language)

Create a complete KQL query from a natural language description:

Examples:

Show me failed sign-ins in the last 24 hours

Count high severity security alerts by type

Find malicious process executions on Windows devices

Get all email phishing attempts from the last week

Show me suspicious PowerShell commands run in the last hour

Parameters:

• query (required): Natural language description of what data you want to query

Returns:

• Complete KQL query automatically generated
• Appropriate table selection based on description
• Relevant filters and conditions
• Aggregations when appropriate

7. Find Column (find_column)

Find which tables contain a specific column:

Examples:

Which tables have the AccountName column?

Find tables containing IPAddress

Where can I find the TimeGenerated column?

Show me tables with the FileName column

Which tables contain ThreatName?

Parameters:

• column_name (required): Name of the column to search for

Returns:

• List of all tables containing the specified column
• Column details for each table
• Data types

8. Get Schema Statistics (get_schema_statistics)

View statistics about the schema index:

Examples:

Show schema statistics

How many tables are in the schema index?

Get schema coverage information

Show me schema index stats

What's the coverage of the schema database?

Returns:

• Total number of tables
• Number of categories
• Coverage by product (Defender XDR, Sentinel, Azure Monitor)
• Additional statistics

Query Generation & Validation Tools (5 tools)

Generate and validate KQL queries with 100% schema verification:

1. generate_kql_query - Generate validated KQL queries from natural language
2. validate_kql_query - Validate existing queries for correctness
3. get_query_documentation - Get Microsoft Learn documentation for queries/tables
4. check_microsoft_docs_mcp - Get Microsoft Docs MCP installation guide
5. search_github_examples_fallback - Search GitHub when table not in schema

1. Generate KQL Query (generate_kql_query)

Generate a fully validated KQL query from natural language description. All table names, column names, and data types are verified against the 331+ table schema index.

Examples:

Generate a KQL query to show failed sign-ins from the last 24 hours

Create a query to find devices with high severity alerts

Generate a query for email events with malicious attachments in the last 7 days

Show me risky sign-ins for admin accounts

Create a query to detect PowerShell execution on devices

Parameters:

• description (required): Natural language description of what you want to query
• table_name (optional): Specific table name if known (e.g., "SigninLogs")
• time_range (optional): Time range filter (e.g., "24h", "7d", "30d")
• columns (optional): Specific columns to include in results
• filters (optional): Additional filters as key-value pairs
• limit (optional): Maximum number of results (default: 100)
• include_aggregations (optional): Include summarization/aggregations

Returns:

• Validated KQL query
• Validation results (errors/warnings)
• Microsoft Learn documentation links
• Query explanation
• Table schema information

2. Validate KQL Query (validate_kql_query)

Validate an existing KQL query for syntax correctness, table validity, column validity, and common mistakes before execution.

Examples:

Validate this query: SigninLogs | where TimeGenerated > ago(24h) | project UserPrincipalName, IPAddress

Check if this KQL query is correct: DeviceProcessEvents | where ProcessCommandLine contains "powershell"

Validate: EmailEvents | where ThreatTypes has "malware" | top 100 by Timestamp

Parameters:

• query (required): The KQL query to validate

Returns:

• Validation status (passed/failed)
• List of errors (if any)
• List of warnings (if any)
• Suggestions for fixes

3. Get Query Documentation (get_query_documentation)

Get Microsoft Learn documentation links for a KQL query or table, including operator documentation and reference guides.

Examples:

Get documentation for SigninLogs table

Show me documentation for this query: DeviceEvents | where ActionType == "ProcessCreated"

Get Microsoft Learn docs for DeviceProcessEvents

Parameters:

• query (optional): KQL query to get documentation for
• table_name (optional): Table name to get documentation for

Returns:

• Table reference documentation link
• Operator documentation links
• General KQL reference
• Source system documentation

4. Check Microsoft Docs MCP (check_microsoft_docs_mcp)

Get information about the Microsoft Docs MCP server and how to install it for enhanced documentation access.

Examples:

How do I install Microsoft Docs MCP?

Tell me about Microsoft Docs MCP integration

What is Microsoft Docs MCP?

Returns:

• What Microsoft Docs MCP is
• Benefits of using it
• Installation instructions
• Configuration examples
• Links to documentation

5. Search GitHub Examples Fallback (search_github_examples_fallback)

Search GitHub for query examples when a table is not in the schema index. Returns unvalidated examples from public repositories.

Examples:

Find GitHub examples for CustomTable that's not in the schema

Search for queries using InternalSecurityEvents table

Parameters:

• table_name (required): Name of the table to search examples for
• description (optional): Additional context for filtering examples

Returns:

• GitHub repository examples
• Warning that examples are unvalidated
• Recommendation to use Microsoft Docs MCP
• Query snippets and context

How It Works

Architecture

┌─────────────────┐
│  Claude Desktop │
│   (MCP Client)  │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  KQL MCP Server │
│                 │
│ ┌─────────────┐ │
│ │Natural Lang │ │
│ │   Parser    │ │
│ └──────┬──────┘ │
│        │        │
│ ┌──────▼──────┐ │
│ │   GitHub    │ │
│ │   Client    │ │
│ └──────┬──────┘ │
│        │        │
│ ┌──────▼──────┐ │
│ │KQL Parser & │ │
│ │   Ranker    │ │
│ └─────────────┘ │
└─────────────────┘
         │
         │ GitHub API
         │
┌────────▼────────┐
│     GitHub      │
│  (All Repos)    │
└─────────────────┘

Search Process

1. Natural Language Processing: Your plain English query is analyzed to extract relevant keywords
2. Query Enhancement: Keywords are combined with KQL-specific terms for optimal GitHub search
3. GitHub Code Search: Searches across all public repositories for relevant KQL files
4. Content Extraction: Fetches file contents from matching repositories
5. KQL Parsing: Intelligently extracts individual KQL queries from files
6. Context Gathering: Collects surrounding comments, documentation , and usage examples
7. Relevance Ranking: Scores queries based on multiple factors:
   • Repository popularity (stars)
   • Query complexity and completeness
   • Documentation quality
   • Search term relevance
8. Results Presentation: Returns formatted, ready-to-use queries with full context

File Extensions Searched

The server automatically searches for these file extensions:

• .kql - Standard KQL query files (modern format, most common)
• .kusto - Kusto query files (alternative format)
• .csl - CSL query files (legacy Kusto format, less common)
• .yaml / .yml - YAML files with embedded KQL (Microsoft Sentinel detection rules)
• .txt - Text files containing KQL queries (Microsoft 365 Defender hunting queries)
• .md - Markdown files with KQL query examples and documentation

Rate Limits

GitHub API has the following rate limits:

• Authenticated requests: 5,000 requests per hour
• Code search: 30 requests per minute

The server automatically tracks and warns about rate limit usage. Use the get_rate_limit tool to check your current status.

Troubleshooting

"GITHUB_TOKEN environment variable is required"

Ensure your GitHub token is properly configured in Claude Desktop's config file with the correct environment variable name.

"GitHub API rate limit nearly exceeded"

You're approaching the API limit. Wait for the reset time shown in the error message, or use the get_rate_limit tool to check status.

"No KQL queries found"

Try:

• Using different or broader search terms
• Checking for typos
• Searching for specific table names or data sources
• Using the search_kql_repositories tool to find relevant repositories first

"The command 'npx' needed to run KQL Search was not found" in VS Code

This error means you're trying to use the npx-based setup instead of the VS Code extension.

Solution: Install the KQL Search MCP extension from the VS Code Marketplace:

1. Open Extensions panel in VS Code (Ctrl+Shift+X / Cmd+Shift+X)
2. Search for "KQL Search MCP"
3. Click Install
4. Run "KQL Search MCP: Set GitHub Token" from Command Palette

The VS Code extension does NOT require Node.js, npm, or npx - it comes fully bundled!

If you prefer using npx: Install Node.js from nodejs.org, then configure using .vscode/mcp.json as shown in the "Setup for GitHub Copilot (MCP Configuration File)" section above.

Server not appearing in Claude Desktop

1. Fully restart Claude Desktop (quit completely and reopen)
2. Verify the config file path is correct:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Check that your GITHUB_TOKEN is valid and has public_repo scope
4. Ensure you have an active internet connection (npx needs to download the package)
5. Check Claude Desktop logs for errors:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs\mcp*.log

Security

• Never commit your GitHub token to the repository
• The token is stored only in Claude Desktop's configuration
• Use tokens with minimal required scopes (public_repo only)
• Rotate tokens regularly

License

MIT License - see LICENSE file for details

Related Projects

• Model Context Protocol - Official MCP documentation
• ugurkocde/KQL-Search - Inspiration for this project
• Microsoft Sentinel KQL Queries - Microsoft's official KQL query repository

Acknowledgments

Inspired by kqlsearch.com by Ugur Koc. This project brings KQL query search to the Model Context Protocol with natural language support and GitHub integration.