MCP Defender (mcp-msdefenderkql)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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
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 resultsRelated 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
From PyPI (Recommended)
pip install mcp-msdefenderkqlFrom 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.exampleto.envFill 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-secretCertificate Setup
For certificate authentication, combine your private key and certificate:
cat private.key cert.pem > combined.pemUsage
Running the Server
mcp-msdefenderkqlTesting with MCP Inspector
npx @modelcontextprotocol/inspector mcp-msdefenderkqlClaude 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 |
| Execute KQL queries against Advanced Hunting |
| 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 ConnectionCountDevelopment
# Run tests
pytest
# Lint code
ruff check .
# Type check
mypy src
# Security scan
bandit -r srcAPI Reference
This server uses the WindowsDefenderATP API:
Endpoint:
https://api.securitycenter.microsoft.comAdvanced Hunting:
POST /api/advancedqueries/run
License
MIT
Available Tools
2 toolsget_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
Scored across 2 tools
The two tools have clearly distinct purposes: one for exploring the schema and one for executing queries. No overlap or ambiguity exists.
Both tools follow a consistent verb_noun pattern ('get_hunting_schema' and 'run_hunting_query'), making them predictable and easy to understand.
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.
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
Official Microsoft MCP Server to query Microsoft Entra data using natural language
An MCP server that integrates with Discord to provide AI-powered features.
AI-powered incident management and server monitoring via MCP.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Related MCP Servers
- AlicenseAqualityBmaintenanceAI-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.2813MIT
- AlicenseNot gradedqualityDmaintenanceA 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.1GPL 3.0
- AlicenseNot gradedqualityBmaintenanceAn MCP server that enables AI assistants to query and manage Microsoft SQL Server databases using natural language.142 npm5MIT
- AlicenseNot gradedqualityDmaintenanceAn 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