Microsoft MCP (resulta.tech fork)

Powerful MCP server for Microsoft Graph API - a complete AI assistant toolkit for Outlook, Calendar, OneDrive, and Contacts.

This is a fork maintained by resulta.tech based on the original work by elyxlz.

Features

• Email Management: Read, send, reply, manage attachments, organize folders
• Batch Operations: Efficiently delete, move, or update multiple emails at once (up to 80% fewer API calls)
• Calendar Intelligence: Create, update, check availability, respond to invitations
• OneDrive Files: Upload, download, browse with pagination
• Contacts: Search and list contacts from your address book
• Multi-Account: Support for multiple Microsoft accounts (personal, work, school)
• Unified Search: Search across emails, files, events, and people

Quick Start with Claude Desktop

# Add Microsoft MCP server (replace with your Azure app ID)
claude mcp add microsoft-mcp -e MICROSOFT_MCP_CLIENT_ID=your-app-id-here -- uvx --from git+https://github.com/klokain/microsoft-mcp.git microsoft-mcp

# Start Claude Desktop
claude

Usage Examples

# Email examples
> read my latest emails with full content
> reply to the email from John saying "I'll review this today"
> send an email with attachment to alice@example.com

# Batch email operations
> delete all emails from this sender at once
> move all emails with subject containing "newsletter" to my archive folder
> mark all unread emails from last week as read

# Calendar examples  
> show my calendar for next week
> check if I'm free tomorrow at 2pm
> create a meeting with Bob next Monday at 10am

# File examples
> list files in my OneDrive
> upload this report to OneDrive
> search for "project proposal" across all my files

# Mail rules examples
> create a rule to move all newsletters to a folder
> list all my active mail rules
> disable the rule that forwards to my assistant
> create a rule to flag emails from my boss as important

# Multi-account
> list all my Microsoft accounts
> send email from my work account

Available Tools

Email Tools

• list_emails - List emails with optional body content
• get_email - Get specific email with attachments
• create_email_draft - Create email draft with attachments support
• send_email - Send email immediately with CC/BCC and attachments
• reply_to_email - Reply maintaining thread context
• reply_all_email - Reply to all recipients in thread
• update_email - Mark emails as read/unread
• move_email - Move emails between folders
• delete_email - Delete emails
• get_attachment - Get email attachment content
• search_emails - Search emails by query

Batch Email Operations

• batch_delete_emails - Delete multiple emails at once (up to 20)
• batch_move_emails - Move multiple emails to a folder efficiently
• batch_update_emails - Update multiple emails (mark read/unread, etc.)

Batch operations use Microsoft Graph JSON batching for optimal performance, automatically handling concurrency limits and providing detailed results for each operation.

Calendar Tools

• list_events - List calendar events with details
• get_event - Get specific event details
• create_event - Create events with location and attendees
• update_event - Reschedule or modify events
• delete_event - Cancel events
• respond_event - Accept/decline/tentative response to invitations
• check_availability - Check free/busy times for scheduling
• search_events - Search calendar events

Contact Tools

• list_contacts - List all contacts
• get_contact - Get specific contact details
• create_contact - Create new contact
• update_contact - Update contact information
• delete_contact - Delete contact
• search_contacts - Search contacts by query

Mail Rule Tools

• list_mail_rules - List all inbox rules
• get_mail_rule - Get specific rule details
• create_mail_rule - Create new mail rule with conditions and actions
• update_mail_rule - Modify existing mail rules
• delete_mail_rule - Remove mail rules
• toggle_mail_rule - Enable/disable rules

File Tools

• list_files - Browse OneDrive files and folders
• get_file - Download file content
• create_file - Upload files to OneDrive
• update_file - Update existing file content
• delete_file - Delete files or folders
• search_files - Search files in OneDrive

Utility Tools

• unified_search - Search across emails, events, and files
• list_accounts - Show authenticated Microsoft accounts
• authenticate_account - Start authentication for a new Microsoft account
• complete_authentication - Complete the authentication process after entering device code

Manual Setup

1. Azure App Registration

1. Go to Azure Portal → Microsoft Entra ID → App registrations
2. New registration → Name: microsoft-mcp
3. Supported account types: Personal + Work/School
4. Authentication → Allow public client flows: Yes
5. API permissions → Add these delegated permissions:
   • Mail.ReadWrite
   • Calendars.ReadWrite
   • Files.ReadWrite
   • Contacts.Read
   • People.Read
   • User.Read
   • MailboxSettings.ReadWrite
6. Copy Application ID

2. Installation

git clone https://github.com/klokain/microsoft-mcp.git
cd microsoft-mcp
uv sync

3. Authentication

# Set your Azure app ID
export MICROSOFT_MCP_CLIENT_ID="your-app-id-here"

# Run authentication script
uv run authenticate.py

# Follow the prompts to authenticate your Microsoft accounts

4. Claude Desktop Configuration

Add to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "microsoft": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/klokain/microsoft-mcp.git", "microsoft-mcp"],
      "env": {
        "MICROSOFT_MCP_CLIENT_ID": "your-app-id-here"
      }
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "microsoft": {
      "command": "uv",
      "args": ["--directory", "/path/to/microsoft-mcp", "run", "microsoft-mcp"],
      "env": {
        "MICROSOFT_MCP_CLIENT_ID": "your-app-id-here"
      }
    }
  }
}

Multi-Account Support

All tools require an account_id parameter as the first argument:

# List accounts to get IDs
accounts = list_accounts()
account_id = accounts[0]["account_id"]

# Use account for operations
send_email(account_id, "user@example.com", "Subject", "Body")
list_emails(account_id, limit=10, include_body=True)
create_event(account_id, "Meeting", "2024-01-15T10:00:00Z", "2024-01-15T11:00:00Z")

Development

# Run tests
uv run pytest tests/ -v

# Type checking
uv run pyright

# Format code
uvx ruff format .

# Lint
uvx ruff check --fix --unsafe-fixes .

Example: AI Assistant Scenarios

Smart Email Management

# Get account ID first
accounts = list_accounts()
account_id = accounts[0]["account_id"]

# List latest emails with full content
emails = list_emails(account_id, limit=10, include_body=True)

# Reply maintaining thread
reply_to_email(account_id, email_id, "Thanks for your message. I'll review and get back to you.")

# Forward with attachments
email = get_email(email_id, account_id)
attachments = [get_attachment(email_id, att["id"], account_id) for att in email["attachments"]]
send_email(account_id, "boss@company.com", f"FW: {email['subject']}", email["body"]["content"], attachments=attachments)

Bulk Email Operations

# Get account ID first
accounts = list_accounts()
account_id = accounts[0]["account_id"]

# Find emails to process
search_results = search_emails(account_id, query="from:newsletter@company.com", limit=50)
email_ids = [email["id"] for email in search_results]

# Batch delete unwanted emails
delete_result = batch_delete_emails(account_id, email_ids)
print(f"Deleted {delete_result['succeeded']} of {delete_result['total']} emails")

# Batch move emails to archive folder
archive_ids = [email["id"] for email in search_emails(account_id, query="older:30d", limit=20)]
move_result = batch_move_emails(account_id, archive_ids, "archive")
print(f"Moved {move_result['succeeded']} emails to archive")

# Batch mark emails as read
unread_ids = [email["id"] for email in list_emails(account_id, limit=10) if not email.get("isRead")]
update_result = batch_update_emails(account_id, unread_ids, {"isRead": True})
print(f"Marked {update_result['succeeded']} emails as read")

# Check detailed results for any failures
for result in update_result["results"]:
    if not result["success"]:
        print(f"Failed to update email {result['email_id']}: {result['error']}")

Intelligent Scheduling

# Get account ID first
accounts = list_accounts()
account_id = accounts[0]["account_id"]

# Check availability before scheduling
availability = check_availability(account_id, "2024-01-15T10:00:00Z", "2024-01-15T18:00:00Z", ["colleague@company.com"])

# Create meeting with details
create_event(
    account_id,
    "Project Review",
    "2024-01-15T14:00:00Z", 
    "2024-01-15T15:00:00Z",
    location="Conference Room A",
    body="Quarterly review of project progress",
    attendees=["colleague@company.com", "manager@company.com"]
)

Automated Email Organization with Rules

# Get account ID first
accounts = list_accounts()
account_id = accounts[0]["account_id"]

# Create rule to organize newsletters
create_mail_rule(
    account_id,
    "Newsletter Management",
    conditions={
        "senderContains": ["newsletter", "noreply", "marketing"],
        "subjectContains": ["unsubscribe", "weekly", "digest"]
    },
    actions={
        "moveToFolder": "Newsletters",
        "markAsRead": False,
        "assignCategories": ["Newsletters"]
    }
)

# Priority email handling
create_mail_rule(
    account_id,
    "VIP Emails",
    conditions={
        "fromAddresses": [
            {"emailAddress": {"address": "ceo@company.com"}},
            {"emailAddress": {"address": "important.client@example.com"}}
        ],
        "importance": "high"
    },
    actions={
        "markImportance": "high",
        "assignCategories": ["VIP", "Urgent"],
        "forwardTo": "assistant@company.com"
    },
    sequence=1  # Process first
)

# Spam filtering rule
create_mail_rule(
    account_id,
    "Spam Filter",
    conditions={
        "bodyOrSubjectContains": ["win", "free", "click here", "limited offer"],
        "senderContains": ["@suspicious-domain.com"]
    },
    actions={
        "moveToFolder": "Junk Email",
        "permanentDelete": False
    }
)

# Meeting request handling
create_mail_rule(
    account_id,
    "Meeting Requests",
    conditions={
        "isMeetingRequest": True,
        "importance": "high"
    },
    actions={
        "assignCategories": ["Meetings", "Calendar"],
        "markImportance": "high"
    }
)

Security Notes

• Tokens are cached locally in ~/.microsoft_mcp_token_cache.json
• Use app-specific passwords if you have 2FA enabled
• Only request permissions your app actually needs
• Consider using a dedicated app registration for production

Troubleshooting

• Authentication fails: Check your CLIENT_ID is correct
• "Need admin approval": Use MICROSOFT_MCP_TENANT_ID=consumers for personal accounts
• Missing permissions: Ensure all required API permissions are granted in Azure
• Mail rules 403 Forbidden: Add MailboxSettings.ReadWrite permission to your Azure app registration
• Token errors: Delete ~/.microsoft_mcp_token_cache.json and re-authenticate

License

MIT