Outlook Server

Fork notice. This repository is a fork of marlonluo2018/outlook-mcp-server with an added draft-first guardrail:

• compose_email_tool, reply_to_email_by_number_tool, and batch_forward_email_tool never send emails. They create drafts in the Outlook Drafts folder and return the draft EntryID. The user must open Outlook and send manually.
• Every draft creation is appended to ~/.outlook-mcp/audit.log (one JSON line per event).

Everything else (search, list folders, move, delete, attachments, viewing) is unchanged from upstream.

---

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

🤔 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:

1. Open Claude Desktop settings
2. Find "MCP Servers" section
3. Click "Add Server" → "Custom"
4. Paste the JSON configuration
5. 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

1. Load emails: "Show me recent emails" → Emails appear in cache
2. Browse results: View 5 emails per page with clear formatting
3. Take action: Reply, move, delete, or get AI summary
4. 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
[email protected]
[email protected]
[email protected]

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 subjects
• search_email_by_sender_name_tool("sender name") - Search by sender
• search_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 details
• reply_to_email_by_number_tool(email_number, "reply text") - Reply to email
• compose_email_tool("[email protected]", "subject", "body") - Send new email

Folder Operations

• get_folder_list_tool() - Always use first to see available folders
• create_folder_tool("folder name") - Create new folder
• move_email_tool(email_number, "target folder") - Move email between folders
• move_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

---