Microsoft Graph MCP Server

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 .

3. Sign In

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

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

Claude will call:

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

2. 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.

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

Claude will call:

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

4. 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

1. 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"
}

2. 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"
}

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

Claude will call:

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

4. 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

1. 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"
}

2. 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

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

Claude will call:

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

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

Claude will call:

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

3. 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

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

Claude will call:

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

2. 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.

3. 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

4. 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

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

Claude will call:

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

2. 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)

3. 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.

4. 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):

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

Claude will call:

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

2. 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.

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

Claude will call:

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

4. View specific email: "Show me email number 3"

Claude will call:

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

5. 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)

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

Claude will call:

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

2. 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.

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

Claude will call:

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

4. 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

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

Claude will call:

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

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

Claude will call:

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

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

Claude will call:

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

4. 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:

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

Calendar Workflow:

1. search_events - Load events into cache
2. browse_events - Browse events
3. get_event_detail - View specific event
4. manage_event_as_attendee or manage_event_as_organizer - Take action

Authentication Workflow:

1. Try auth with refresh action FIRST - if authenticated, proceed
2. If refresh fails (no token or expired): auth with start → get verification URL and code
3. Open URL in browser, enter the code, complete Microsoft login
4. 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.

---