M365 MCP Server

A Model Context Protocol (MCP) server for Microsoft 365 administration using the Microsoft Graph API.

🚀 Features

• User Management: Create, read, update, delete users and their mailboxes
• Microsoft 365 Groups: Full CRUD operations for Microsoft 365 Groups, including member and owner management
• Shared Mailboxes: List and manage shared mailboxes (read-only via Graph API, PowerShell required for member management)
• Mailbox Operations: Delegate mailboxes and convert user mailboxes to shared (PowerShell instructions provided)
• Enhanced Error Handling: Comprehensive error reporting with troubleshooting guidance and Graph API limitation explanations

🛠️ Setup

1. Azure App Registration

1. Go to Azure Portal → "Azure Active Directory" → "App registrations"
2. Click "New registration"
3. Name your application
4. Supported account types: "Accounts in this organizational directory only"
5. Click "Register"

2. Configure Permissions

1. Go to "API permissions" in your app registration

2. Click "Add a permission" → "Microsoft Graph" → "Application permissions"

3. Add these required permissions:

   User Management:

   • User.ReadWrite.All - Required for all user operations (create, read, update, delete users)
   • Directory.ReadWrite.All - Required for user directory operations and license management

   Group Management:

   • Group.ReadWrite.All - Required for Microsoft 365 Groups operations (create, manage members/owners)

   Mailbox Operations:

   • MailboxSettings.ReadWrite.All - Required for mailbox settings and calendar permissions

   License Management:

   • User.ReadWrite.All (already listed above) - Covers license assignment operations

4. Click "Grant admin consent for [Your Organization]"

3. Important Notes About Permissions

⚠️ Graph API Limitations:

• Shared Mailboxes: Cannot add/remove members via Graph API - requires Exchange Online PowerShell
• Mailbox Delegation: Cannot delegate mailbox access via Graph API - requires Exchange Online PowerShell
• Distribution Lists: Cannot manage members via Graph API - requires Exchange Online PowerShell
• Mailbox Type Conversion: Cannot convert mailbox types via Graph API - requires Exchange Online PowerShell

✅ What Works with Graph API:

• User creation, updates, deletion
• Microsoft 365 Groups management
• Basic mailbox settings retrieval
• License assignment and removal
• User account enable/disable

4. Create Client Secret

1. Go to "Certificates & secrets" in your app registration
2. Click "New client secret"
3. Description: MCP Server Secret
4. Expiration: Choose appropriate duration
5. Copy the Value (not the ID) - this is your CLIENT_SECRET

5. Get Credentials

Copy these values from your app registration:

• Application (client) ID → CLIENT_ID
• Directory (tenant) ID → TENANT_ID
• Client Secret Value → CLIENT_SECRET

🚀 Installation

1. Install Dependencies

pip3 install -r requirements.txt

2. Configure Environment

Create a .env file:

TENANT_ID=your_tenant_id_here
CLIENT_ID=your_client_id_here
CLIENT_SECRET=your_client_secret_here

3. Run the Server

python3 m365_mcp_server.py

🖥️ Claude Desktop Integration

Add this to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "m365-admin": {
      "command": "python3",
      "args": ["/path/to/your/m365-mcp/m365_mcp_server.py"],
      "env": {
        "TENANT_ID": "your_tenant_id_here",
        "CLIENT_ID": "your_client_id_here",
        "CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

🔍 Troubleshooting

PowerShell Requirements

Many operations require Exchange Online PowerShell:

• Shared mailbox member management
• Mailbox delegation
• Distribution list member management
• Mailbox type conversion

To install Exchange Online PowerShell:

Install-Module -Name ExchangeOnlineManagement
Connect-ExchangeOnline

Common Error Codes

• 401 Unauthorized: Token expired or insufficient permissions
• 403 Forbidden: Missing API permissions or admin consent not granted
• 404 Not Found: Resource doesn't exist or email address is incorrect
• 400 Bad Request: Invalid request format or missing required properties
• 409 Conflict: Resource already exists

Authentication Issues

1. Check Environment Variables: Ensure all three variables are set
2. Verify App Registration: Confirm app exists and has correct permissions
3. Grant Admin Consent: Ensure admin consent is granted for all permissions
4. Check Client Secret: Verify secret is valid and not expired

API Permission Issues

1. Review Permissions: Ensure all required permissions are added:
   • User.ReadWrite.All
   • Directory.ReadWrite.All
   • Group.ReadWrite.All
   • MailboxSettings.ReadWrite.All
2. Check Permission Type: Use "Application permissions" not "Delegated permissions"
3. Grant Admin Consent: Click "Grant admin consent" in Azure Portal
4. Wait for Propagation: Changes may take up to 15 minutes to propagate

Graph API Limitations

Expected Behaviors (Not Errors):

• Shared mailbox member management fails: This is expected - use PowerShell Add-MailboxPermission
• Mailbox delegation fails: This is expected - use PowerShell Add-MailboxPermission
• Distribution list member management fails: This is expected - use PowerShell Add-DistributionGroupMember
• Mailbox type conversion fails: This is expected - use PowerShell Set-Mailbox -Type Shared

Common Issues

• "pip command not found": Use pip3 instead of pip
• "Permission denied" (403): Ensure admin consent is granted for all permissions
• "Resource not found" (404): Check if the user/group exists and verify email addresses
• "Unsupported query" (400): Usually indicates Graph API limitation - use PowerShell instead
• "Authorization denied" (403): Check if the operation is supported by Graph API
• Microsoft 365 Group membership restrictions: Some groups may have restricted membership management
• Shared mailbox operations: Most shared mailbox operations require Exchange Online PowerShell