🤖 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 agent_prompt_template.md 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 template 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"
🛠️ Essential Tools
Email Search & Loading
list_recent_emails_tool(days=7)- Load recent emails (max: 30 days)search_email_by_subject_tool("search term")- Search email subjectssearch_email_by_sender_name_tool("sender name")- Search by sendersearch_email_by_body_tool("search term")- Search email content (slower)
Email Actions
view_email_cache_tool(page=1)- Browse loaded emails (5 per page)get_email_by_number_tool(email_number)- Get full email detailsreply_to_email_by_number_tool(email_number, "reply text")- Reply to emailcompose_email_tool("recipient@email.com", "subject", "body")- Send new email
Folder Operations
get_folder_list_tool()- Always use first to see available folderscreate_folder_tool("folder name")- Create new foldermove_email_tool(email_number, "target folder")- Move email between foldersmove_folder_tool("source", "target")- Move folders
Safety Notes
- Always check folder list first before moving/deleting
- Emails are cached - use numbers from cache for operations
- Never sends without confirmation - AI always asks before sending
⚡ Performance
- Loads 100 emails in ~2 seconds
- Searches complete in real-time
- All processing happens locally (your data stays private)
✅ Quality & Reliability
Robust Validation System
- Input Validation: All user inputs are validated before processing
- Custom Error Messages: Clear, actionable error messages for common issues
- Safety Checks: Prevents invalid operations before they cause problems
Comprehensive Testing
- 145+ Unit Tests: Every feature thoroughly tested
- Configuration Coverage: All settings and constants validated
- Edge Case Handling: Tested against unusual inputs and scenarios
- Continuous Quality: Tests run on every change to ensure reliability
What This Means for You
- Fewer Errors: Validation catches mistakes before they cause problems
- Better Error Messages: Know exactly what went wrong and how to fix it
- Reliable Operation: Comprehensive testing ensures consistent performance
- Safe Operations: Built-in safeguards prevent accidental data loss
🛡️ Privacy & Security
- 100% Local Processing: No data leaves your computer
- No Cloud Services: Works entirely offline
- Secure by Design: Uses your existing Outlook installation
📚 Need Help?
- Check the agent prompt template for AI assistant setup
- See configuration examples for different installation methods
- Read the Win32COM vs Graph API comparison for technical details
- Review Win32COM API implementation guide for performance optimization
- Report issues on the GitHub repository
⭐ Love saving time on email? Star this repo - helps 10,000+ Outlook users discover AI email management! ⭐
💡 Quick star tip: Click the ⭐ button above - it takes 2 seconds and supports open-source email AI!