mcp-msdefenderkql 1.0.1

MCP server for Microsoft Defender Advanced Hunting - execute KQL queries via natural language

MCP Defender

mcp-name: io.github.trickyfalcon/mcp-msdefenderkql

An MCP (Model Context Protocol) server for Microsoft Defender Advanced Hunting. Enables AI assistants to investigate security events using natural language by translating queries to KQL and executing them against Defender.

How It Works

User: "Show me suspicious PowerShell activity in the last hour"
  ↓
AI translates to KQL using schema knowledge
  ↓
MCP executes query against Defender API
  ↓
AI interprets and explains the results

Features

• Advanced Hunting: Execute KQL queries against Defender's Advanced Hunting API
• Dynamic Schema Discovery: Fetch available tables and columns directly from your Defender instance
• Natural Language Security Investigations: Let AI translate your questions into KQL
• Certificate Authentication: Secure authentication using Azure AD certificates (recommended)

Prerequisites

• Python 3.10+
• Azure AD App Registration with WindowsDefenderATP permission:
  • AdvancedQuery.Read.All - Run advanced queries

Installation

From PyPI (Recommended)

pip install mcp-msdefenderkql

From Source

# Clone the repository
git clone https://github.com/trickyfalcon/mcp-defender.git
cd mcp-defender

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Configuration

1. Copy .env.example to .env
2. Fill in your Azure AD credentials:

AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id

# Option 1: Certificate authentication (recommended)
AZURE_CLIENT_CERTIFICATE_PATH=/path/to/combined.pem

# Option 2: Client secret authentication
# AZURE_CLIENT_SECRET=your-client-secret

Certificate Setup

For certificate authentication, combine your private key and certificate:

cat private.key cert.pem > combined.pem

Usage

Running the Server

mcp-msdefenderkql

Testing with MCP Inspector

npx @modelcontextprotocol/inspector mcp-msdefenderkql

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "defender": {
      "command": "/path/to/mcp-defender/.venv/bin/python",
      "args": ["-m", "mcp_defender.server"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-defender/src",
        "AZURE_TENANT_ID": "your-tenant-id",
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_CLIENT_CERTIFICATE_PATH": "/path/to/combined.pem"
      }
    }
  }
}

Available Tools

Tool	Description
run_hunting_query	Execute KQL queries against Advanced Hunting
get_hunting_schema	Get available tables and columns dynamically

Example Natural Language Queries

Once connected to Claude, you can ask:

• "Show me any suspicious PowerShell activity in the last hour"
• "Find devices with failed login attempts"
• "What processes are making network connections to external IPs?"
• "List all devices that haven't checked in for 7 days"

Example KQL Queries

// Find failed logon attempts
DeviceLogonEvents
| where ActionType == "LogonFailed"
| where Timestamp > ago(24h)
| summarize FailedAttempts = count() by AccountName, DeviceName
| top 10 by FailedAttempts

// Detect suspicious PowerShell
DeviceProcessEvents
| where FileName in~ ("powershell.exe", "pwsh.exe")
| where ProcessCommandLine has_any ("encodedcommand", "bypass", "hidden", "downloadstring")
| project Timestamp, DeviceName, AccountName, ProcessCommandLine

// Network connections to external IPs
DeviceNetworkEvents
| where RemoteIPType == "Public"
| where Timestamp > ago(1h)
| summarize ConnectionCount = count() by DeviceName, RemoteIP
| top 20 by ConnectionCount

Development

# Run tests
pytest

# Lint code
ruff check .

# Type check
mypy src

# Security scan
bandit -r src

API Reference

This server uses the unified Microsoft 365 Defender API:

• Endpoint: https://api.security.microsoft.com
• Advanced Hunting: POST /api/advancedqueries/run

License

MIT