How do I use MCP Defender (mcp-msdefenderkql)?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Defender (mcp-msdefenderkql) Find devices with failed login attempts in the last 24 hours" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

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

Copy .env.example to .env
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

MCP Defender (mcp-msdefenderkql)