Enterprise Microsoft 365 MCP Server
by ManoAlee
README.md
<div align="center">
# ⚡ Enterprise Microsoft 365 MCP Server
**The definitive, production-grade Model Context Protocol (MCP) server for enterprise Microsoft 365, Exchange Online, Microsoft Entra ID, and Microsoft Graph administration.**
[](https://opensource.org/licenses/MIT)
[](https://python.org)
[-blueviolet.svg?style=for-the-badge)](https://modelcontextprotocol.io)
[](#-tool-catalog-66-tools)
[](https://learn.microsoft.com/en-us/graph/)
[](https://learn.microsoft.com/en-us/powershell/exchange/)
[](#-security--enterprise-governance)
<p align="center">
<a href="#-key-capabilities">Key Capabilities</a> •
<a href="#-architecture">Architecture</a> •
<a href="#-meta-mcp-self-evolution--tool-synthesis">Meta-MCP Engine</a> •
<a href="#-quickstart">Quickstart</a> •
<a href="#-tool-catalog-66-tools">Tool Catalog (66 Tools)</a> •
<a href="#-client-configuration">Client Setup</a> •
<a href="#-security--enterprise-governance">Security</a> •
<a href="#-contributing">Contributing</a>
</p>
</div>
---
## 🌟 Overview
The **Enterprise Microsoft 365 MCP Server** connects Large Language Models (LLMs) and autonomous AI coding agents (such as **Claude Desktop**, **Cursor**, **Antigravity IDE**, **Cline**, and **GitHub Copilot**) directly to enterprise Microsoft 365 tenants with institutional-grade security.
Equipped with **66 specialized tools across 21 operational pillars**, it fuses:
1. **Microsoft Graph REST API** (v1.0 & Beta) for ultra-fast, modern directory, messaging, calendar, files, and org awareness.
2. **Exchange Online Management v3 REST Engine** for deep administrative operations, transport rules, litigation holds, quarantine management, and mail flow forensics.
3. **Adaptive Execution & Reverse Engineering Engine** for zero-script execution, dynamic object reflection, and mail loop elimination.
4. **Meta-MCP Dynamic Synthesis Engine** for creating and hot-reloading new tools and scaffolding standalone MCP servers on the fly.
5. **SMTP & Messaging Infrastructure Engine** for low-level socket diagnostics, real-time SMTP AUTH credential validation, Direct Send testing, and DNS security posture auditing (MX, SPF, DMARC, anti-spoofing).
---
## 🚀 Key Capabilities
```
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ENTERPRISE M365 CAPABILITIES │
├──────────────────────────────┬──────────────────────────────┬───────────────────────────────────┤
│ 📅 Vacation & OOF Automation │ 🛡️ EOP Quarantine & Security │ 👥 Entra ID & User Lifecycle │
│ • Scheduled HTML auto-replies│ • Threat message release │ • Ex-employee shared conversion │
│ • Date-bounded forward rules │ • Tenant Allow/Block Lists │ • Org hierarchy & reporting lines │
│ • Multi-language signatures │ • Phish/Spam remediation │ • Never-expiring service creds │
├──────────────────────────────┼──────────────────────────────┼───────────────────────────────────┤
│ ⚡ SMTP & Relay Engineering │ ⚖️ Compliance & Forensics │ 📁 OneDrive & SharePoint (ODSP) │
│ • Real-time SMTP AUTH test │ • Litigation hold audits │ • File inventory & search │
│ • Direct Send MX verification│ • Recoverable items purge │ • Drive item metadata extraction │
│ • SPF, MX & DMARC DNS health │ • Message trace (24-72h) │ • Corporate document auditing │
├──────────────────────────────┼──────────────────────────────┼───────────────────────────────────┤
│ 📬 Mailbox Deep Governance │ 📆 Calendar & Meetings │ 💬 Teams & Notification Webhooks │
│ • Delegate & SendAs rights │ • Meeting scheduling │ • Adaptive Card alerts │
│ • Shared mailbox automapping │ • Real-time calendar events │ • Daily operations digest bot │
│ • Folder retention & counts │ • Availability inspection │ • Incident dispatch channels │
└──────────────────────────────┴──────────────────────────────┴───────────────────────────────────┘
```
---
## 🏛️ Architecture
```
┌─────────────────────────────────────────┐
│ AI Agents & Coding Assistants │
│ (Claude, Cursor, Antigravity, Cline) │
└────────────────────┬────────────────────┘
│ MCP Protocol (JSON-RPC stdio)
▼
┌─────────────────────────────────────────┐
│ Enterprise M365 MCP Server Core │
│ FastMCP • Pydantic • RBAC │
└───────┬────────────┬────────────┬───────┘
│ │ │
┌────────────────┘ │ └────────────────┐
▼ ▼ ▼
┌────────────────────────┐ ┌───────────────────────────┐ ┌────────────────────────┐
│ Microsoft Graph Engine│ │ Exchange Online Bridge │ │ SMTP & DNS Diagnostics │
│ OAuth2 App Client │ │ EXO v3 REST PowerShell │ │ Sockets • RFC 5321 │
│ • Directory & Org │ │ • Transport Rules │ │ • Port 25 / 587 Check │
│ • Mail, Calendar, ODSP│ │ • Quarantine & Holds │ │ • Real-time SMTP AUTH │
│ • Credential Policies │ │ • Mailbox Protocols │ │ • MX, SPF & DMARC Audit│
└────────────────────────┘ └───────────────────────────┘ └────────────────────────┘
```
---
## ⚡ Quickstart
### 1. Prerequisites
* **Python 3.10+**
* An **App Registration in Microsoft Entra ID** with Graph permissions (e.g., `Directory.Read.All`, `Mail.ReadWrite`, `User.ReadWrite.All`)
* Exchange Online Administrator rights (if utilizing PowerShell Exchange features)
### 2. Installation
Clone and install dependencies:
```bash
git clone https://github.com/ManoAlee/MCP-M365-MICROSOFT.git
cd MCP-M365-MICROSOFT
pip install -r requirements.txt
```
### 3. Configuration (Zero-Trust Security)
Create a `.env` file or export environment variables:
```bash
export M365_TENANT_ID="00000000-0000-0000-0000-000000000000"
export M365_CLIENT_ID="00000000-0000-0000-0000-000000000000"
export M365_CLIENT_SECRET="your-azure-app-client-secret"
export M365_PRIMARY_ADMIN="admin@yourdomain.com"
export MCP_LOG_LEVEL="INFO"
```
*Alternatively, copy `config.example.json` to `config.json` (strictly ignored by `.gitignore`).*
---
## 🛠️ Tool Catalog (58 Tools)
### 1. Out of Office / Vacation Automation
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_get_vacation_status` | Exchange | Queries scheduled auto-reply status and forward rules. |
| `m365_configure_vacation` | Exchange | Schedules HTML auto-reply and optional date-bounded redirect rules. |
| `m365_disable_vacation` | Exchange | Immediately deactivates out-of-office autoreply and cleans temporary rules. |
### 2. Lifecycle & Ex-Employee Governance
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_audit_ex_employees` | Exchange | Audits offboarded user mailboxes, shared status, and forwarding rules. |
| `m365_convert_ex_employee_to_shared` | Exchange | Converts user mailbox to Shared Mailbox and sets forwarding target. |
### 3. Mailbox Operations & Permissions
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_get_mailbox_info` | Exchange | Deep inspection of mailbox type, protocols (OWA, MAPI, SMTP AUTH), and aliases. |
| `m365_list_mailboxes` | Exchange | Lists tenant mailboxes filtered by type (`UserMailbox`, `SharedMailbox`, `RoomMailbox`). |
| `m365_configure_shared_mailbox` | Exchange | Grants `FullAccess`, `SendAs`, configures automapping and Sent Items copy. |
### 4. Transport Rules & Mail Routing
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_list_inbox_rules` | Exchange | Lists all client-side Inbox Rules configured on a user's mailbox. |
| `m365_list_transport_rules` | Exchange | Lists tenant-wide Exchange Transport / Mail Flow rules with priority. |
| `m365_remove_inbox_rule` | Exchange | Removes a specific inbox rule by name or GUID. |
### 5. Microsoft Graph Email & Teams Notifications
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `graph_send_email` | Graph API | Dispatches emails via Microsoft Graph REST API (`/sendMail`) with HTML & attachments. |
| `graph_list_recent_messages` | Graph API | Fetches recent messages from Inbox or custom folders with OData query filters. |
| `graph_send_teams_notification` | Webhook | Sends high-impact Teams Adaptive Cards to operational webhooks. |
### 6. Directory, GAL & External Contacts
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `gal_search_directory_users` | Graph API | Searches Global Address List (GAL) users by displayName, email, or department. |
| `gal_audit_external_mail_contacts` | Exchange | Audits Mail Contacts in the directory against authoritative local registry. |
### 7. Compliance, Retention & Legal Hold
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `compliance_audit_signatures` | Graph API | Audits user profile attributes mapped to corporate signature policies. |
| `compliance_audit_retention` | Exchange | Audits retention policies, hold statuses, and litigation hold flags. |
| `compliance_audit_litigation_hold` | Exchange | Identifies all mailboxes currently placed under active Litigation Hold. |
| `compliance_audit_mailbox_recoverable_items`| Exchange | Audits Recoverable Items folder quotas and purge activity. |
### 8. Mail Flow, Message Trace & DKIM
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_message_trace` | Exchange | Runs Exchange Message Trace (24-72h) diagnosing delivery failures and NDRs. |
| `m365_verify_dkim_status` | Exchange | Validates DKIM signing status, selector records, and key rotation. |
| `m365_list_connectors` | Exchange | Inspects Inbound and Outbound connectors, TLS validation, and sender IPs. |
### 9. Exchange Online Protection (EOP) & Quarantine
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_check_quarantine` | Exchange | Queries quarantined messages filtered by reason (`Phish`, `Spam`, `Malware`). |
| `m365_list_tenant_allow_list` | Exchange | Lists tenant allow/block entries for senders, domains, and URLs. |
| `m365_add_sender_to_allow_list` | Exchange | Adds safe sender or domain to the Tenant Allow List with expiration. |
### 10. Groups & Distribution Lists
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_list_distribution_groups` | Exchange | Lists Distribution Groups, Mail-Enabled Security Groups, and M365 Groups. |
| `m365_get_group_members` | Exchange | Retrieves full member rosters and ownership for any group. |
| `m365_manage_group_member` | Exchange | Adds or removes member UPNs from a Distribution Group. |
| `m365_set_group_external_delivery` | Exchange | Toggles `RequireSenderAuthenticationEnabled` to permit external inbound mail. |
### 11. Licensing & SKU Management
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_list_license_skus` | Graph API | Audits subscribed SKUs, total enabled seats, consumed units, and pool availability. |
### 12. Profile Sync & Organization Management
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_get_user_profile` | Graph API | Queries full Entra ID profile (department, title, office, phone, manager). |
| `m365_update_user_profile` | Exchange/Entra | Updates corporate directory fields and syncs Exchange Address Book. |
### 13. Operational Intelligence & Bot
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `graph_generate_daily_activity_summary` | Graph API | Analyzes recent mailbox traffic and compiles structured operational digests. |
### 14. Advanced Mailbox Diagnostics & Routing Forensics
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `graph_inspect_mailbox_folders` | Graph API | Recursively inspects mailbox folder hierarchy with item counts and size. |
| `graph_diagnose_mailbox_health` | Graph API | Automated forensic diagnosis of message delivery destinations and rules. |
| `graph_search_mailbox_messages` | Graph API | Searches mailbox messages using KQL, subject keywords, or sender criteria. |
### 15. Calendar & Meeting Management
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_list_calendar_events` | Graph API | Retrieves calendar events in a date window with attendee RSVP statuses. |
| `m365_create_calendar_event` | Graph API | Creates enterprise meetings with Teams link, attendees, and HTML body. |
### 16. OneDrive & SharePoint Files (ODSP)
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_list_onedrive_files` | Graph API | Lists files and folders in a user's OneDrive root or specific subfolder. |
| `m365_search_onedrive_files` | Graph API | Searches documents across OneDrive and SharePoint drives by keyword. |
### 17. Organizational Hierarchy & Management Tree
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_get_user_manager` | Graph API | Retrieves a user's direct line manager from the organizational chart. |
| `m365_get_user_direct_reports` | Graph API | Retrieves all direct reports assigned to a supervisor or executive. |
| `m365_get_department_members` | Graph API | Lists all corporate directory users belonging to a specific department. |
### 18. SMTP Diagnostics, Authentication, Test Delivery & DNS Health ⚡
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_test_smtp_connectivity` | Network/Socket | Tests TCP socket reachability, DNS resolution, and ESMTP EHLO handshake (ports 25, 587, 465) with latency and STARTTLS verification. |
| `m365_test_smtp_auth` | SMTP Engine | Validates SMTP AUTH credentials in real time with root-cause diagnostic guidance for code 535 (licensing, MFA, basic auth policies). |
| `m365_send_smtp_test_email` | SMTP Engine | Sends end-to-end test emails supporting Direct Send (port 25, unauthenticated) or SMTP AUTH (port 587, authenticated). |
| `m365_audit_domain_dns_health` | DNS Engine | Audits domain email DNS health (MX, SPF, DMARC), assesses spoofing risks, and cross-references public WAN IP against authorized SPF entries. |
| `m365_get_password_policy` | Graph API | Queries Microsoft Entra ID via Graph API to determine if a service account has `DisablePasswordExpiration` enabled. |
| `m365_set_password_never_expires`| Graph/PowerShell | Sets or revokes `DisablePasswordExpiration` policy for automated service accounts. |
| `m365_diagnose_smtp_relay_prerequisites` | Hybrid Engine | Pre-flight audit for SMTP Relay & Direct Send (WAN IP, MX, ports 25/587, Inbound Connectors, and SPF). |
### 19. Advanced Rules & Email Loop Elimination 🔄
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_get_inbox_rule_details` | Exchange Online | Retrieves complete properties, conditions, dates, and exceptions for any mailbox inbox rule. |
| `m365_set_inbox_rule` | Exchange Online | Updates conditions, actions, and exceptions (`ExceptIfSentTo`) of an inbox rule to permanently break email loops and duplicate deliveries. |
### 20. Adaptive Execution Engine & Object Reverse-Engineering 🔍
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_adaptive_exchange_executor` | Exchange Online | Dynamically executes any Exchange Online cmdlet or pipeline on-demand with automatic JSON parsing and error recovery (zero scratch scripts). |
| `m365_reverse_inspect_object` | Hybrid Reflection | Reverse-engineers and inspects any M365/Exchange entity (Mailbox, Group, Rule, Contact), resolving members, aliases, protocols, and rules. |
| `m365_inspect_message_routing` | Graph API | Inspects transport headers (`X-MS-Exchange-Inbox-Rules-Loop`, `Return-Path`) and detects email loops and duplicate deliveries in real time. |
| `m365_adaptive_graph_query` | Graph API | Executes any custom REST request against Microsoft Graph API v1.0 using the MCP authentication token. |
### 21. Meta-MCP: Tool Synthesis & Server Scaffolding 🧬
| Tool | Engine | Description |
| :--- | :---: | :--- |
| `m365_create_tool` | Meta-MCP Synthesizer | Synthesizes, validates, and registers a new tool dynamically in runtime with AST syntax validation, persistence, and JSON schema output. |
| `m365_create_server` | Meta-MCP Generator | Scaffolds the complete architecture for a new standardized MCP Server for other enterprise subsystems (FastMCP, core, tools, tests). |
---
## 🧬 Meta-MCP: Self-Evolution & Tool Synthesis
The Enterprise M365 MCP Server includes a **Meta-MCP Runtime Layer** that empowers AI coding agents with self-evolution and dynamic capability expansion:
```
┌────────────────────────────────────────────────────────────────────────┐
│ META-MCP SELF-EVOLUTION ENGINE │
├────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Introspect & Reverse-Engineer │
│ m365_reverse_inspect_object ──► Discovers unknown entity types │
│ │
│ 2. Execute Without Friction (Zero Scripts) │
│ m365_adaptive_exchange_executor ──► Runs cmdlets on-the-fly │
│ m365_adaptive_graph_query ────────► Queries REST endpoints │
│ │
│ 3. Synthesize & Persist Capabilities │
│ m365_create_tool ──► Writes, validates AST, hot-reloads tool │
│ m365_create_server ─► Scaffolds complete new MCP ecosystems │
│ │
└────────────────────────────────────────────────────────────────────────┘
```
* **Zero-Script Operation**: Eliminates the fragile anti-pattern of creating temporary `.ps1` or `.py` scratch files on the host filesystem.
* **Hot-Reload Tool Creation**: Synthesizes and tests new tools in `src/mcp_m365/tools/dynamic/` directly via AI conversation.
* **Instant Loop Remediation**: Automatically detects routing loops via `m365_inspect_message_routing` and patches them surgically with `m365_set_inbox_rule`.
## 💻 Client Configuration
Add this server to your preferred MCP environment:
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"m365-governance": {
"command": "python",
"args": ["-m", "mcp_m365.server"],
"cwd": "/path/to/MCP-M365-MICROSOFT",
"env": {
"M365_TENANT_ID": "your-tenant-id",
"M365_CLIENT_ID": "your-client-id",
"M365_CLIENT_SECRET": "your-client-secret",
"M365_PRIMARY_ADMIN": "admin@yourdomain.com"
}
}
}
}
```
### Cursor (`.cursor/mcp.json`)
```json
{
"mcpServers": {
"m365-governance": {
"command": "python",
"args": ["-m", "mcp_m365.server"],
"cwd": "${workspaceFolder}"
}
}
}
```
### Antigravity IDE (`mcp_config.json`)
```json
{
"mcpServers": {
"m365-governance": {
"command": "python.exe",
"args": ["-m", "mcp_m365.server"],
"cwd": "C:\\path\\to\\MCP-M365-MICROSOFT"
}
}
}
```
---
## 🔒 Security & Enterprise Governance
This repository adheres to strict **Zero-Trust & Zero-Leak** security standards:
1. **Zero Hardcoded Secrets**: Absolutely no client IDs, secrets, tenant GUIDs, employee PII, or company domain names exist in the codebase. All runtime identity is injected strictly via environment variables.
2. **Robust `.gitignore` Guardrails**: Production configuration files (`config.json`, `.env`, `*.token_cache.bin`, logs) are enforced in `.gitignore`.
3. **Least Privilege Principle**: Supports granular Azure App Registration permission scopes. Read operations require only `Directory.Read.All` and `Mail.ReadWrite`.
4. **Defensive SMTP Testing**: Diagnostic test email utilities do not store credentials or bypass transport policies.
---
## 🧪 Testing & Validation
The server includes a comprehensive automated test suite verifying tool registration, Pydantic schemas, and Graph/Exchange integrations:
```bash
# Run unit tests
python -m unittest discover tests
# Output:
# ..............
# ----------------------------------------------------------------------
# Ran 14 tests in 0.004s
# OK (66 Tools Operational)
```
---
## 📄 License
Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for details.
---
<div align="center">
<b>Built for Enterprise Cloud Architects, SecOps & AI Engineers</b><br>
Maintained by <a href="https://github.com/ManoAlee">Alessandro Meneses (@ManoAlee)</a>
</div>
TDQS
C2.9/5.0
Scored across 34 tools
Disambiguation4/5
Most tools target distinct resources and actions, such as vacation status vs. configure vs. disable, or message trace vs. quarantine checks. However, several audit and directory tools have adjacent purposes (e.g., compliance audits, GAL search vs. user profile lookup, transport rules vs. domain signature audit), so occasional confusion is possible.
Naming Consistency3/5
Tools generally use snake_case verb_noun phrasing, which is readable and mostly predictable. But the server mixes multiple prefix families (m365_, graph_, gal_, compliance_) and some names are long audit-style descriptions rather than consistent action-oriented patterns.
Tool Count2/5
At 34 tools, the surface is heavy for an MCP server and risks overwhelming tool selection. While Microsoft 365 administration is broad, many tools are narrow audit or configuration variants that could be consolidated or grouped.
Completeness3/5
The set covers a wide range of Exchange Online, Entra ID, Defender, compliance, and Graph operations, including many read and audit capabilities. However, it lacks several core lifecycle operations such as mailbox/user/group creation and deletion, license assignment, and broader Teams or SharePoint management.
Maintenance
ActivityMaintained
ResponsivenessNo issues