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

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 GitHub Copilot (VS Code)

Requirements: GitHub Copilot subscription and VS Code 1.102+

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 21 tools in your MCP client:

GitHub Search Tools (8 tools)

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

Server not appearing in Claude

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.