Skip to main content
Glama
trickyfalcon

MCP Defender (mcp-msdefenderkql)

by trickyfalcon
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

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 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
table_nameNoGet detailed schema for a specific table

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes that it returns table names, column names, and data types. No annotations provided, but the description is clear and implies a safe read operation. Could be improved by explicitly stating no side effects or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences: purpose, usage guidance, return content. No unnecessary information. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description fully covers what the tool does, when to use it, and what it returns. No gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already describes the parameter. The description adds minimal value by implying the parameter is optional, but does not provide additional semantic context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Get' and resource 'Advanced Hunting schema', and distinguishes from sibling tool 'run_hunting_query' by specifying it is for understanding data before writing queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to call this before writing queries, providing clear when-to-use guidance. Differentiates from the sibling tool for running queries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe KQL query to execute

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It states the tool executes a query for investigation, implying read-only behavior, but does not explicitly disclose non-obvious traits such as whether it is destructive, authorization requirements, rate limits, or error handling. This lack of detail limits the agent's ability to assess impacts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with two focused sentences. The first sentence defines the core action and purpose, and the second provides a crucial prerequisite. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter and no output schema, the description covers the essential aspects: what the tool does, its domain, and a prerequisite. It could briefly mention that results are returned, but overall it provides sufficient context for an agent to understand its use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage with one parameter ('query') described as 'The KQL query to execute'. The description adds no further semantics beyond restating 'KQL query', so it meets the baseline but does not enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Execute a KQL query') and its resource ('Microsoft Defender Advanced Hunting'). It also specifies its use case ('investigate security events') and distinguishes it from the sibling tool by instructing to call get_hunting_schema first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers a clear usage guideline: 'Always call get_hunting_schema first to understand available tables and columns.' This helps the AI agent know when and how to use the tool. However, it does not explicitly state when not to use it or provide alternative scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.0.0
    • First observedget_hunting_schema
    • First observedrun_hunting_query
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • wazuh-mcp-server

    Sbharadwaj05
    A
    license
    A
    quality
    C
    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

  • LevelBlue USM Anywhere MCP

    javierb507
    F
    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
    -

  • mssql-mcp

    eamonboyle
    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.
    252
    5
    MIT

  • AI Detection Engineering

    Simoon896
    A
    license
    Not graded
    quality
    B
    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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/trickyfalcon/mcp-defender'

If you have feedback or need assistance with the MCP directory API, please join our Discord server