microsoft/purview-dlm-mcp

microsoft/purview-dlm-mcp

Language: TypeScript

License: MIT

Stars: 8

Forks: 5

Open issues: 23

Created: 2026-03-01T12:14:13Z

Pushed: 2026-06-20T03:50:22Z

Default branch: main

Fork: no

Archived: no

README:

Microsoft Purview DLM Diagnostics MCP

An MCP (Model Context Protocol) server for diagnosing Microsoft Purview Data Lifecycle Management issues via Exchange Online PowerShell.

Features

• 5 MCP tools — run_powershell for executing read-only Exchange Online commands, get_execution_log for retrieving a full audit trail, ask_learn for Microsoft Learn documentation lookup, create_issue for reporting issues with the MCP server to GitHub, and submit_feedback for collecting structured diagnostic session feedback
• 11 TSG reference guides — step-by-step diagnostic workflows aligned to common DLM symptoms
• 72 diagnostic checks — automated evaluation engine that parses PowerShell output and produces structured findings with remediation
• Cmdlet allowlist — only pre-approved read-only cmdlets can be executed; mutating commands are blocked

Prerequisites

• Node.js 18+
• PowerShell 7
• ExchangeOnlineManagement PowerShell module (v3.4+)
• An admin account with the required permissions (see [Required Permissions](#required-permissions) below)

Required Permissions

The authenticating user (DLM_UPN) needs read access to both Exchange Online and Security & Compliance PowerShell sessions.

Recommended Role Combinations

| Option | Roles | Notes | |--------|-------|-------| | Least-privilege | Global Reader + Compliance Administrator | Recommended — covers both EXO and S&C read access | | Single role group | Organization Management | Covers both workloads but broader than necessary | | Full admin | Global Administrator | Works but overly broad — not recommended |

Why Both Workloads?

The server connects to two PowerShell sessions:

• Exchange Online (Connect-ExchangeOnline) — cmdlets like Get-Mailbox, Get-MailboxStatistics, Export-MailboxDiagnosticLogs, Get-OrganizationConfig
• Security & Compliance (Connect-IPPSSession) — cmdlets like Get-RetentionCompliancePolicy, Get-RetentionComplianceRule, Get-AdaptiveScope, Get-ComplianceTag

Exchange cmdlets require EXO roles; compliance cmdlets require S&C roles. Without both, some diagnostics will fail with permission errors.

Authentication

The server uses MSAL interactive browser sign-in — a browser window opens for the user to authenticate. No credentials are stored or passed via environment variables.

Licensing Requirements

Some diagnostics require specific licensing on target mailboxes:

| Feature | Required License | |---------|-----------------| | Archive diagnostics | Exchange Online Archiving or E3/E5 | | Adaptive scopes | E5 Compliance or E5 Information Protection & Governance | | Teams retention | Microsoft 365 E3+ |

Quick Start

npx -y @microsoft/purview-dlm-mcp

Set DLM_UPN and DLM_ORGANIZATION in your MCP client config (see below).

MCP Client Configuration

Claude Desktop

Add this to your claude_desktop_config.json:

{
"mcpServers": {
"dlm-diagnostics": {
"command": "npx",
"args": ["-y", "@microsoft/purview-dlm-mcp"],
"env": {
"DLM_UPN": "admin@yourtenant.onmicrosoft.com",
"DLM_ORGANIZATION": "yourtenant.onmicrosoft.com",
"DLM_COMMAND_TIMEOUT_MS": "180000"
}
}
}
}

VS Code

Add this to your .vscode/settings.json or user settings:

{
"mcp": {
"servers": {
"dlm-diagnostics": {
"command": "npx",
"args": ["-y", "@microsoft/purview-dlm-mcp"],
"env": {
"DLM_UPN": "admin@yourtenant.onmicrosoft.com",
"DLM_ORGANIZATION": "yourtenant.onmicrosoft.com",
"DLM_COMMAND_TIMEOUT_MS": "180000"
}
}
}
}
}

Available Tools

| Tool | Description | |------|-------------| | run_powershell | Execute a read-only Exchange Online PowerShell command against the allowlist | | get_execution_log | Retrieve the log of all commands executed during the current session | | ask_learn | Look up Microsoft Purview documentation on Microsoft Learn (fallback when no TSG matches) | | create_issue | Report an issue with the MCP server to GitHub, attaching session diagnostic context | | submit_feedback | Submit structured feedback about a diagnostic session (emits telemetry, no PII) |

Tool Examples

run_powershell

> User: "Archiving is not working on john.doe@contoso.com"

The AI uses run_powershell to investigate step by step:

✅ Step 1 — Check mailbox archive status
Command: Get-Mailbox -Identity john.doe@contoso.com | FL ArchiveStatus, ArchiveState, RetentionPolicy
Finding: ArchiveStatus = Active, ArchiveState = Local

✅ Step 2 — Check archive mailbox size
Command: Get-MailboxStatistics -Identity john.doe@contoso.com -Archive | FL DisplayName, TotalItemSize, ItemCount
Finding: TotalItemSize = 98.5 GB (4,231 items)

⚠️ Step 3 — Check auto-expanding archive
Command: Get-Mailbox -Identity john.doe@contoso.com | FL AutoExpandingArchiveEnabled
Finding: AutoExpandingArchiveEnabled = False — archive is near 100 GB limit

Root Cause: Archive is near quota and auto-expanding archive is not enabled.
Recommended Action: Enable auto-expanding archive at the org level.

get_execution_log

> User: "Show me all the commands that were run during this investigation"

Returns a Markdown-formatted audit trail:

## Execution Log (3 entries)

| # | Time | Command | Duration | Status |
|---|------|---------|----------|--------|
| 1 | 14:23:01 | Get-Mailbox -Identity john.doe@contoso.com | 2.1s | ✅ |
| 2 | 14:23:04 | Get-MailboxStatistics -Identity john.doe@contoso.com -Archive | 1.8s | ✅ |
| 3 | 14:23:06 | Get-Mailbox -Identity john.doe@contoso.com \| FL AutoExpandingArchiveEnabled | 1.5s | ✅ |

ask_learn

> User: "How do I create a retention policy in Purview?"

The AI uses ask_learn to find relevant documentation:

## Retention Policies

Create and configure retention policies to automatically retain or delete content.

### Key Steps
1. Go to Microsoft Purview compliance portal → Data lifecycle management → Retention policies
2. Select "New retention policy" and configure locations (Exchange, SharePoint, OneDrive, Teams, etc.)
3. Choose whether to retain...