Outlook MCP Server by marlonluo2018 - MCP Server

🤖 Outlook MCP Server

AI-powered email management for Microsoft Outlook - Search, compose, organize, and batch forward emails with natural language commands.

⭐ This saved you time? Star us - takes 2 seconds, helps thousands of Outlook users find this AI email assistant! ⭐

🤔 Project Choice: Local vs Cloud Approach

This project uses win32COM which works entirely locally with your Outlook data (more secure), while our new Microsoft Graph MCP Server provides online access to the full Microsoft 365 ecosystem (more features). Choose based on your security and functionality needs.

Why Choose This Project (win32COM)?

✅ Local Data Processing: All email operations happen locally on your computer - no data leaves your machine
✅ Enhanced Security: No cloud authentication or API tokens required - works with your existing Outlook setup
✅ Offline Capability: Access and manage emails even without internet connection
✅ Privacy-First: Your email data never touches external servers or cloud services

Why Switch to Microsoft Graph API?

✅ Full Microsoft 365 Ecosystem: Access Mail, Calendar, Teams, OneDrive, SharePoint
✅ Cross-Platform Support: Works on Windows, macOS, Linux, and mobile devices
✅ Modern Authentication: OAuth 2.0 with device code flow
✅ Cloud-Scale Performance: No local application dependencies
✅ Online Access: Works directly with cloud-based Microsoft 365 services

🚀 Quick Start (2 Minutes)

What You'll Get

Smart Email Search: "Find emails about budget approval from last week"
AI Email Writing: Draft replies with context-aware suggestions
Easy Organization: Create folders and move emails with simple commands
Batch Forwarding: Send emails to 100s of recipients in minutes, not hours

🤖 AI Behavior & Workflow

The defines how the AI assistant behaves when managing emails:

Purpose: Guide the AI's workflow for email search, summarization, and drafting
Key Rules: AND logic for searches, 5-by-5 email display, confirmation before sending
Safety: Built-in constraints ensure user control and prevent unauthorized actions
How to Use: Copy the template content and use it to configure your AI assistant

See the for complete behavior guidelines and workflow definitions

Why Choose Outlook MCP Server?

Feature	Outlook MCP Server	Traditional Outlook	Outlook Add-ins
AI Email Search	✅ "Find urgent emails from my boss"	❌ Manual folder browsing	⚠️ Basic search only
Natural Language	✅ "Show me budget emails from last week"	❌ Complex filters needed	⚠️ Limited keywords
Batch Forward 100+ Emails	✅ 2 minutes with CSV	❌ 50+ minutes manual	⚠️ 20+ minutes
AI Email Writing	✅ Context-aware replies	❌ Manual composition	⚠️ Basic templates
Setup Time	✅ 2 minutes	✅ Already installed	❌ 10-30 minutes
Privacy	✅ 100% local processing	✅ Local only	⚠️ Cloud-dependent
Cost	✅ Completely free	✅ Included	💰 $5-50/month
Learning Curve	✅ Natural language	✅ Familiar interface	⚠️ New interface

Real-World Impact

Before: "I need to forward this email to 150 team members..."

Manual: Click Forward → Type each email → Send → 2+ hours wasted
Traditional Outlook: Create distribution list → Add members → Forward → 30+ minutes

After: "Forward this email to everyone in team.csv"

Outlook MCP Server: Load CSV → AI forwards to all → 2 minutes total
Time Saved: 48+ minutes per batch operation!

Requirements

✅ Python 3.8+
✅ Microsoft Outlook 2016+ (must be running)
✅ Windows 10+

Installation & Setup

Method 1: UVX (Recommended - Auto Dependencies)

# 1. Install
git clone https://github.com/marlonluo2018/outlook-mcp-server.git
cd outlook-mcp-server
uvx --with "pywin32>=226" --with-editable "." outlook-mcp-server

# 2. Configure your AI assistant
# Use this in your MCP client settings:
{
  "mcpServers": {
    "outlook": {
      "command": "uvx",
      "args": ["--with", "pywin32>=226", "--with-editable", ".", "outlook-mcp-server"]
    }
  }
}

Method 2: Standard Python

# 1. Install
git clone https://github.com/marlonluo2018/outlook-mcp-server.git
cd outlook-mcp-server
pip install -r requirements.txt
python -m outlook_mcp_server

# 2. Configure your AI assistant
# Use this in your MCP client settings:
{
  "mcpServers": {
    "outlook": {
      "command": "python",
      "args": ["-m", "outlook_mcp_server"]
    }
  }
}

Method 3: Direct Source (Development)

# 1. Install
git clone https://github.com/marlonluo2018/outlook-mcp-server.git
cd outlook-mcp-server
pip install -r requirements.txt

# 2. Configure your AI assistant
# Use this in your MCP client settings:
{
  "mcpServers": {
    "outlook": {
      "command": "python",
      "args": ["C:\\Project\\outlook-mcp-server\\outlook_mcp_server\\__main__.py"]
    }
  }
}

Test Your Setup ✅

Ask your AI assistant: "Show me my recent emails" - if it works, you're ready!

Configuration Troubleshooting 🛠️

Common Issues & Solutions:

Problem	Check This	Solution
"uvx not found"	Is UV installed?	`pip install uv` then retry
"python not found"	Python in PATH?	Use full path like `C:\Python39\python.exe`
"Outlook not running"	Outlook window open?	Start Outlook first, then restart MCP
"Permission denied"	Admin rights?	Run terminal as administrator
"Module not found"	Dependencies installed?	`pip install -r requirements.txt`

Configuration Verification:

# Test your setup before connecting to AI
python -c "import outlook_mcp_server; print('✅ Server module loaded')"

# Test Outlook connection (Windows only)
python -c "import win32com.client; outlook = win32com.client.Dispatch('Outlook.Application'); print('✅ Outlook connected')"

MCP Client-Specific Setup:

Claude Desktop:

Open Claude Desktop settings
Find "MCP Servers" section
Click "Add Server" → "Custom"
Paste the JSON configuration
Restart Claude Desktop

Other MCP Clients:

Look for "MCP Configuration" or "Server Settings"
Add the JSON to your client's config file
Usually located at: ~/.config/[client]/mcp.json

Still Stuck? Report an issue with your error message and setup details.

🎯 Core Features

Email Management

Search: Find emails by subject, sender, content, or date range
Compose: Write new emails with AI assistance
Reply: Smart replies that understand conversation context
Batch Forward: Send emails to 100s of recipients from CSV files (saves hours!)

Folder Management

List: See all your Outlook folders
Create: Make new folders with simple commands
Move: Organize emails between folders
Delete: Remove folders (careful - this is permanent!)

📧 Batch Forwarding: Save Hours on Email Distribution

Real-World Use Cases

🎯 Team Updates

Forward weekly reports to your entire team
Send important updates to all team members
Distribute project updates to stakeholders

📊 Marketing Campaigns

Send newsletters to subscriber lists
Forward promotional emails to customer segments
Distribute event invitations to contact groups

🏢 Corporate Communications

Send policy updates to all employees
Forward training materials to departments
Distribute announcements to company distribution lists

🔄 How It Works

Simple Workflow

Load emails: "Show me recent emails" → Emails appear in cache
Browse results: View 5 emails per page with clear formatting
Take action: Reply, move, delete, or get AI summary
Confirm before sending: AI always asks before sending emails

AI Assistant Behavior

Understands natural language: "Find urgent emails from my boss"
Shows email summaries: One-line overview + key action items
Drafts with context: Replies understand the conversation
Never sends without permission: Always confirms before sending

Batch Forwarding Workflow

1. Prepare Your CSV File

email
john@company.com
jane@company.com
team@company.com

2. Use Natural Language

"Forward this email to everyone in my contacts.csv"
"Send this project update to my team list"
"Distribute this newsletter to subscribers.csv"

3. AI Handles the Rest

Automatically splits large lists (max 500 per batch)
Sends via BCC to protect recipient privacy
Adds your custom message before original email
Provides delivery confirmation

Time Savings

Manual forwarding: 100 emails × 30 seconds = 50 minutes Batch forwarding: 30 seconds setup + 2 minutes processing = 2.5 minutes You save: 47.5 minutes per batch!

🔧 Common Commands

Try these with your AI assistant:

"Show me emails from last 3 days"
"Find emails about project updates" 
"Draft a reply to John about rescheduling"
"Create a folder called 'Work Projects'"
"Move email #3 to the Archive folder"