Skip to main content
Glama
MCP Defender (mcp-msdefenderkql)

MCP Defender (mcp-msdefenderkql)

by trickyfalcon

MCP Defender

PyPI version License: MIT

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

Related MCP server: LevelBlue USM Anywhere MCP Server

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

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 WindowsDefenderATP API:

  • Endpoint: https://api.securitycenter.microsoft.com

  • Advanced Hunting: POST /api/advancedqueries/run

License

MIT

Available Tools

2 tools
get_hunting_schemaA

Get the Advanced Hunting schema with available tables and columns. Call this before writing queries to understand what data is available. Returns table names, column names, and data types.

Inputs: table_name.

run_hunting_queryA

Execute a KQL (Kusto Query Language) query against Microsoft Defender Advanced Hunting. Use this to investigate security events across endpoints, email, identity, and cloud apps. Always call get_hunting_schema first to understand available tables and columns.

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one for exploring the schema and one for executing queries. No overlap or ambiguity exists.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun pattern ('get_hunting_schema' and 'run_hunting_query'), making them predictable and easy to understand.

    Tool Count3/5

    With only 2 tools, the server feels minimal. While it covers the core workflow (schema discovery + query execution), additional tools for result handling or query management could enhance the set.

    Completeness3/5

    The tools cover the basic hunting loop (schema first, then query), but missing features like saving queries, paginating results, or managing sessions leave notable gaps for a security investigation tool.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      AI-powered MCP server that enables security analysts to query Wazuh SIEM/XDR for alert triage, threat hunting, compliance audits, and incident response through natural language prompts.
      28
      13
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A production-ready MCP server that connects AI assistants to LevelBlue's USM Anywhere security platform, enabling advanced security queries, investigation management, and threat analysis through natural language.
      1
      GPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that enables AI assistants to query and manage Microsoft SQL Server databases using natural language.
      142 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables conversational interaction with Wazuh SIEM, allowing users to investigate alerts, hunt threats, tune false positives, edit rules, and run security actions via natural language.
      MIT