Microsoft Graph MCP Server

March 23, 2026 · View on GitHub

A beautifully simple way to give your AI assistant superpowers inside Microsoft 365.

This project turns Microsoft Graph into an easy‑to‑use MCP server — so Claude, your custom agents, or any MCP client can instantly work with your Email, Calendar, and Contacts.

No Azure setup. No Graph API knowledge. Just install → sign in → your AI becomes a Microsoft 365 power user.

⭐ Why Developers Love This Project

Your AI can read, search, reply to, and organize email naturally
Batch email operations — delete or archive multiple emails in ONE call (no more one-by-one!)
It understands and manages your calendar with real availability checks
It handles contacts with simple MCP tools
It works securely using Microsoft's device login — no secrets, no risk
It just works on local machines with zero configuration

This is the fastest way to make your AI agent actually useful at work.

If this project saves you time:
👉 Please star the repo — it really helps! ⭐

🚀 Quick Start

1. Install

pip install -r requirements.txt

Multimodal Support: Image compression requires Pillow>=10.0.0 (included in requirements.txt). If not installed, images will be returned without compression.

Or:

pip install uv
uvx .

2. Link to Claude Desktop

Open:

%APPDATA%/Claude/claude_desktop_config.json

Choose one of the following configuration methods:

Method 1: Using `uv run` (Recommended)

{
  "mcpServers": {
    "microsoft-graph": {
      "command": "uv",
      "args": ["run", "--directory", "<path-to-your-local-repo>", "microsoft-graph-mcp-server"]
    }
  }
}

Recommended: This method uses your local code directly, so changes take effect immediately without reinstalling.

Method 2: Using `uvx` (Local Path)

{
  "mcpServers": {
    "microsoft-graph": {
      "command": "uvx",
      "args": ["--from", "<path-to-your-local-repo>", "microsoft-graph-mcp-server"]
    }
  }
}

Note:

First time or after code changes, run: uv tool install --force <path-to-your-local-repo>

uvx caches the package, so you need to reinstall to pick up code updates

Method 3: Using `python -m`

{
  "mcpServers": {
    "microsoft-graph": {
      "command": "py",
      "args": ["-m", "microsoft_graph_mcp_server"]
    }
  }
}

Note:

Windows: Use py (Python Launcher) which automatically finds your Python installation

Linux/Mac: Replace py with python or python3

Run from the project directory or install via pip install -e .

In Claude, simply ask: "Please help me sign in to Microsoft Graph"

Claude will call:

{
  "tool": "auth",
  "action": "start"
}

Follow the link → enter the code → sign in.
Then tell Claude: "I have completed the browser login"

Then Claude will finalize:

{
  "tool": "auth",
  "action": "complete"
}

You're connected. Your AI assistant now has Microsoft 365 access.

🌟 What Your AI Can Do

Below is the friendly but complete feature overview — designed to impress potential users and help people understand the project's power at a glance.

🔧 Configure AI Assistant (Recommended)

Copy the system prompt to your AI assistant configuration:

SYSTEM_PROMPT.md

For Claude Desktop, add to your project or custom instructions. This provides:

Smart workflow selection (AI auto-chooses Quick Mode for simple emails, Full Mode for complex ones)
HTML formatting rules for emails
Calendar conflict detection awareness
Best practices for using MCP tools

For other AI assistants, use the SYSTEM_PROMPT.md content as system instructions.

📧 Email Superpowers

Your AI can:

Search emails by sender, subject, body, or natural filters
Focused Inbox support - by default searches "focused" emails, with option to search "other" or all
Open full email content including attachments
Download attachments to workspace for LLM analysis (Excel, PDF, images, etc.)
Image analysis for multimodal LLMs - View and analyze image attachments inline (screenshots, photos, diagrams)
Reply, forward, and compose new messages with HTML
Move, delete, archive, or bulk‑manage messages
Browse emails with fast local caching
Filter by time ranges ("today", "this week", "last 30 days")
Handle folders: create, rename, delete, move

Example

{
  "tool": "search_emails",
  "query": "invoices",
  "search_type": "subject"
}

Attachment Download Example

{
  "tool": "get_email_content",
  "cache_number": 1,
  "download_attachments": true
}

Attachments are saved to workspace/attachments and can be processed by other tools (file readers, image viewers, etc.).

Focused Inbox Example

{
  "tool": "search_emails",
  "query": "newsletter",
  "inference_classification": "other"
}

📅 Calendar Intelligence

Your AI can:

Search all upcoming events
Create or modify meetings
Cancel events and notify attendees
Accept or decline invitations
Check availability for multiple attendees
Create recurring events
Handle timezones automatically

Example

{
  "tool": "manage_event_as_organizer",
  "action": "create",
  "subject": "Project Sync",
  "start": "2026-02-26T14:00",
  "end": "2026-02-26T14:30"
}

👥 Contact Search

Find people in your organization by name or email
Fallback to fuzzy matching when needed
Works instantly after login

{
  "tool": "search_contacts",
  "query": "john li"
}

🧠 Why This Project Exists

Modern AI assistants need to interact with your real work tools — email, meetings, files.
Microsoft Graph offers all of this, but:

The API is complex
Authentication is intimidating
Azure app registration is painful
Developers want simplicity, not bureaucracy

This MCP server solves all of it:

Zero Azure setup
Zero Graph API learning curve
Zero complexity

Just install and go.

🔥 Real‑World Use Cases & AI‑Friendly Workflows

These practical examples show potential users exactly why this project matters, with workflows designed specifically for AI usage — simple, predictable, and reliable.

Use Case: "Automated Reporting Agent"

Your AI can scan your inbox and calendar, then build a weekly summary report.

Pull last week's emails
Extract key events
Identify action items
Draft a clean weekly summary email
Send it to your team

Workflow

Ask Claude to search emails: "Find emails from the last 7 days"

Claude will call:

{
  "tool": "search_emails",
  "days": 7
}

Ask Claude to browse the results: "Analyze the emails for me"

Claude will call:

{
  "tool": "browse_email_cache",
  "page_number": 1,
  "mode": "llm"
}

Returns: Email summaries with sender, subject, date, and cache numbers for easy reference. In llm mode, Claude gets more emails per page (default 20) for efficient analysis.

Ask Claude to search events: "Find calendar events from last week"

Claude will call:

{
  "tool": "search_events",
  "time_range": "last_week"
}

Ask Claude to send summary email: "Send a weekly summary to the team"

Claude will call:

{
  "tool": "send_email",
  "action": "send_new",
  "to": ["team@example.com"],
  "subject": "Weekly Summary",
  "htmlbody": "<p>Here's the update...</p>"
}

Use Case: Batch BCC Forward

Your AI can search for emails and forward them to multiple recipients via BCC using a CSV file.

Workflow

Ask Claude to search emails by subject: "Find emails with subject 'Company Announcement'"

Claude will call:

{
  "tool": "search_emails",
  "query": "Company Announcement",
  "search_type": "subject"
}

Ask Claude to browse the email cache: "Show me the emails with subject 'Company Announcement'"

Claude will call:

{
  "tool": "browse_email_cache",
  "page_number": 1,
  "mode": "llm"
}

Ask Claude to verify email content: "Show me email number 1"

Claude will call:

{
  "tool": "get_email_content",
  "cache_number": 1
}

Ask Claude to batch forward via BCC using CSV: "Forward email number 1 to all recipients in the CSV file"

Claude will call:

{
  "tool": "send_email",
  "action": "forward",
  "cache_number": 1,
  "bcc_csv_file": "C:/path/to/recipients.csv",
  "subject": "Fwd: Company Announcement",
  "htmlbody": "<p>Please see the company announcement below.</p>"
}

Note: The CSV file should have a single column with header 'Email' containing all recipient email addresses.

Use Case: Schedule a Meeting

Your AI can check availability and schedule meetings with Teams links.

Workflow

Ask Claude to check attendee availability: "Check availability for John and Jane on March 1st"

Claude will call:

{
  "tool": "check_attendee_availability",
  "attendees": ["john@example.com", "jane@example.com"],
  "date": "2026-03-01"
}

Ask Claude to schedule a meeting: "Schedule a meeting with John and Jane on March 1st at 2 PM for 30 minutes"

Claude will call:

{
  "tool": "manage_event_as_organizer",
  "action": "create",
  "subject": "Project Discussion",
  "start": "2026-03-01T14:00",
  "end": "2026-03-01T14:30",
  "attendees": ["john@example.com", "jane@example.com"],
  "team": true
}

Note: The "team": true parameter adds a Teams meeting link to the event.

Use Case: Clean Up Your Inbox

Your AI can help you batch delete or archive multiple emails in one operation.

Workflow

Ask Claude to search emails: "Find emails from newsletter@example.com"

Claude will call:

{
  "tool": "search_emails",
  "query": "newsletter@example.com",
  "search_type": "sender"
}

Ask Claude to browse the results: "Show me these emails"

Claude will call:

{
  "tool": "browse_email_cache",
  "page_number": 1,
  "mode": "llm"
}

Ask Claude to delete multiple emails: "Delete emails 1, 2, 3, 4, and 5"

Claude will call:

{
  "tool": "manage_emails",
  "action": "delete_multiple",
  "cache_numbers": [1, 2, 3, 4, 5]
}

Or archive them instead: "Archive emails 1 through 5"

Claude will call:

{
  "tool": "manage_emails",
  "action": "archive_multiple",
  "cache_numbers": [1, 2, 3, 4, 5]
}

Note: All emails are processed in ONE batch call - efficient and fast!

Use Case: Download and Analyze Attachments

Your AI can download email attachments and analyze them with other tools.

Workflow

Ask Claude to search emails with attachments: "Find emails with Excel attachments"

Claude will call:

{
  "tool": "search_emails",
  "query": "xlsx",
  "search_type": "body"
}

Ask Claude to browse the results: "Show me these emails"

Claude will call:

{
  "tool": "browse_email_cache",
  "page_number": 1,
  "mode": "llm"
}

Returns: Email summaries with attachment info (name, size, contentType) visible upfront.

Ask Claude to download attachments: "Download the Excel attachment from email number 1"

Claude will call:

{
  "tool": "get_email_content",
  "cache_number": 1,
  "download_attachments": true,
  "attachment_names": ["report.xlsx"]
}

Returns: Email content with attachment saved to workspace/attachments/report.xlsx

Use other tools to analyze: "Read the Excel file and summarize it"

Claude can now use file reading tools to process the downloaded attachment.

Key Features:

See attachment names/types before downloading (in browse_email_cache)
Download only specific attachments with attachment_names parameter
Custom download path with download_path parameter
Inline attachments (embedded images) are automatically skipped

Use Case: Analyze Image Attachments (Multimodal)

Your AI can view and analyze image attachments directly when using a multimodal LLM.

Workflow

Ask Claude to search emails with images: "Find emails with image attachments"

Claude will call:

{
  "tool": "search_emails",
  "days": 7
}

Ask Claude to browse the results: "Show me the emails"

Claude will call:

{
  "tool": "browse_email_cache",
  "page_number": 1,
  "mode": "llm"
}

Returns: Email summaries showing attachment types (e.g., contentType: image/png)

Ask Claude to view the email with images: "Show me email number 1 with the images"

Claude will call:

{
  "tool": "get_email_content",
  "cache_number": 1,
  "return_html": true
}

Returns: Email content with images returned as ImageContent for multimodal LLMs to analyze directly.

Claude analyzes the images: "What's in the screenshot?"

Claude will describe what it sees in the images - screenshots, diagrams, photos, charts, etc.

Configuration (in .env):

MULTIMODAL_SUPPORTED=true
IMAGE_MAX_SIZE_KB=50
IMAGE_MAX_DIMENSION=1024
IMAGE_QUALITY=75

Note: Images are automatically compressed to fit within LLM API limits.

User Mode Email Browsing

For human browsing (when you want to see emails page by page):

Ask Claude to search emails: "Find emails from this week"

Claude will call:

{
  "tool": "search_emails",
  "time_range": "this_week"
}

Ask Claude to browse page by page: "Show me the first page of emails"

Claude will call:

{
  "tool": "browse_email_cache",
  "page_number": 1,
  "mode": "user"
}

Returns: Email summaries with sender, subject, date, and cache numbers. In user mode, you get fewer emails per page (default 5) for easier human reading.

Navigate to next page: "Show me the next page"

Claude will call:

{
  "tool": "browse_email_cache",
  "page_number": 2,
  "mode": "user"
}

View specific email: "Show me email number 3"

Claude will call:

{
  "tool": "get_email_content",
  "cache_number": 3
}

Ask Claude to reply to the email: "Reply to email number 3 saying thank you"

Claude will call:

{
  "tool": "send_email",
  "action": "reply",
  "cache_number": 3,
  "htmlbody": "<p>Thank you!</p>"
}

Key difference: Use "mode": "user" when you want to browse emails manually, page by page, with smaller page sizes that are easier for humans to read.

Email Workflow (LLM Mode)

Ask Claude to search emails: "Find emails about budget"

Claude will call:

{
  "tool": "search_emails",
  "query": "budget"
}

Ask Claude to browse the results: "Show me the budget emails"

Claude will call:

{
  "tool": "browse_email_cache",
  "page_number": 1,
  "mode": "llm"
}

Returns: Email summaries with sender, subject, date, and cache numbers for easy reference. In llm mode, Claude gets more emails per page (default 20) for efficient analysis.

Ask Claude to view specific email: "Show me the second email"

Claude will call:

{
  "tool": "get_email_content",
  "cache_number": 2
}

Ask Claude to reply: "Reply to this email saying it looks good"

Claude will call:

{
  "tool": "send_email",
  "action": "reply",
  "cache_number": 2,
  "htmlbody": "<p>Looks good!</p>"
}

Calendar Workflow

Ask Claude to search events: "Find calendar events from this week"

Claude will call:

{
  "tool": "search_events",
  "time_range": "this_week"
}

Ask Claude to browse events: "Show me the first page of events"

Claude will call:

{
  "tool": "browse_events",
  "page_number": 1,
  "mode": "user"
}

Ask Claude to view event details: "Show me event number 1"

Claude will call:

{
  "tool": "get_event_detail",
  "cache_number": 1
}

Ask Claude to respond to event: "Accept event number 1"

Claude will call:

{
  "tool": "manage_event_as_attendee",
  "action": "accept",
  "cache_number": 1
}

🙌 Want to Support the Project?

If this helps you, please consider starring the repository.
It motivates ongoing development and helps others discover the tool.

� Complete MCP Tool Reference

Here's a comprehensive list of all available MCP tools with simple explanations:

🔐 Authentication & Settings

auth - Manage Microsoft Graph authentication (start, complete, refresh, logout)
user_settings - Configure user preferences like timezone, search days, and page sizes

📧 Email Management

search_emails - Search or list emails by sender, subject, body, or time range. Supports Focused Inbox filtering (focused, other, all). Use end_date="now" to search from a specific date until current time
browse_email_cache - Browse cached emails with pagination (user mode for humans, llm mode for AI analysis)
get_email_content - Get full email content including attachments. Use return_html=true to get full HTML body
send_email - Send new emails, replies, or forwards with HTML support
manage_emails - Move, delete, archive, flag, or categorize emails
manage_mail_folder - Create, rename, delete, or move email folders

📅 Calendar Management

search_events - Search or list calendar events by subject or organizer
browse_events - Browse cached calendar events with pagination
get_event_detail - Get detailed information for specific events
manage_event_as_organizer - Create, update, cancel, forward, or email attendees for your own events
manage_event_as_attendee - Accept, decline, tentatively accept, propose new times, email attendees, or delete cancelled event invitations
check_attendee_availability - Check availability for meeting scheduling

👥 People & Contacts

search_contacts - Find people in your organization by name or email

🔑 Key Workflow Patterns

Email Workflow:

search_emails - Load emails into cache
browse_email_cache - Browse with appropriate mode (llm for AI, user for humans)
get_email_content - View specific email details
send_email or manage_emails - Take action

Calendar Workflow:

search_events - Load events into cache
browse_events - Browse events
get_event_detail - View specific event
manage_event_as_attendee or manage_event_as_organizer - Take action

Authentication Workflow:

Try auth with refresh action FIRST - if authenticated, proceed
If refresh fails (no token or expired): auth with start → get verification URL and code
Open URL in browser, enter the code, complete Microsoft login
auth with complete action → authentication finished

Note: Refresh tokens are valid for ~90 days. Always try refresh first when authentication is needed.

All tools follow the JSON format with "tool": "tool_name" as the first parameter, making them easy to use with AI assistants like Claude.