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

Related MCP server: M365 MCP

🛠️ 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