Email Processing MCP Server
A cross-platform MCP server that processes Microsoft Outlook emails, generates vector embeddings using Ollama, and provides semantic search capabilities. Works on Windows, macOS, and any platform via Microsoft Graph API.
The server complies with the Model Context Protocol (MCP) 2025-06-18 specification and uses the official MCP SDK.
Features
Core Capabilities
- Process emails from Outlook with date range filtering
- Store emails in SQLite database with proper connection management
- Generate vector embeddings using Ollama (nomic-embed-text)
- Semantic search across email content via MongoDB vector store
- Multi-mailbox and multi-account support
- Support for Inbox, Sent Items, and optionally Deleted Items folders
Cross-Platform Support
- Windows: Native Outlook COM automation via pywin32
- macOS: AppleScript integration with Outlook for Mac
- Any Platform: Microsoft Graph API for cloud-based access (Windows, macOS, Linux, containers)
MCP 2025-06-18 Compliance
- Structured Tool Results: Tools return properly typed, validated Pydantic models
- HTTP Transport: Supports both STDIO and HTTP (Streamable HTTP) transports
- Protocol Negotiation: Declares protocol version during handshake
- Enhanced Metadata: Tool titles and descriptions for better UI integration
Available Tools (12+)
| Category | Tools |
|---|---|
| Email Processing | process_emails |
| Search & Analysis | search_emails, analyze_email_sentiment, find_actionable_items |
| Data Export | export_email_data (CSV, JSON, HTML, Excel) |
| Folder Management | list_outlook_folders, get_folder_statistics, organize_emails_by_rules |
| Contact Management | extract_contacts |
| Statistics | get_email_statistics, check_data_consistency |
Prerequisites
Required (All Platforms)
- Python 3.10 or higher
- Ollama running locally with
nomic-embed-textmodel - MongoDB server (for storing embeddings)
Platform-Specific Requirements
| Platform | Requirement |
|---|---|
| Windows | Microsoft Outlook installed + pywin32 |
| macOS | Microsoft Outlook for Mac installed |
| Graph API | Azure AD app registration with Mail.Read permission |
Installation
1. Install uv (if not already installed)
pip install uv
2. Create and activate virtual environment
uv venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
3. Install dependencies
Core installation (required):
uv pip install -e .
Platform-specific extras:
# Windows (adds pywin32 for COM automation)
uv pip install -e ".[windows]"
# Graph API support (cross-platform cloud access)
uv pip install -e ".[graph]"
# All optional dependencies
uv pip install -e ".[all]"
4. Install Ollama embedding model
ollama pull nomic-embed-text
5. (Graph API only) Register Azure AD Application
If using Microsoft Graph API, you need to register an application in Azure AD:
- Go to Azure Portal → Azure Active Directory → App registrations
- Click "New registration"
- Name your app and select "Accounts in this organizational directory only"
- After creation, note the Application (client) ID and Directory (tenant) ID
- Go to "Certificates & secrets" → "New client secret" → note the secret value
- Go to "API permissions" → "Add a permission" → "Microsoft Graph" → "Application permissions"
- Add:
Mail.Read,User.Read.All(for multi-account discovery) - Click "Grant admin consent"
Configuration
Add the server to your Claude for Desktop configuration file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Environment Variables
| Variable | Description | Required |
|---|---|---|
MONGODB_URI | MongoDB connection string | Yes |
SQLITE_DB_PATH | Path to SQLite database file | Yes |
EMBEDDING_BASE_URL | Ollama server URL (default: http://localhost:11434) | No |
EMBEDDING_MODEL | Embedding model name (default: nomic-embed-text) | No |
COLLECTION_NAME | MongoDB collection name | Yes |
PROCESS_DELETED_ITEMS | Process Deleted Items folder (default: "false") | No |
OUTLOOK_PROVIDER | Provider: auto, windows, mac, graph (default: "auto") | No |
LOCAL_TIMEZONE | Timezone for dates (default: "UTC", e.g., "America/Chicago") | No |
Graph API Variables (required when OUTLOOK_PROVIDER=graph):
| Variable | Description |
|---|---|
GRAPH_CLIENT_ID | Azure AD application (client) ID |
GRAPH_CLIENT_SECRET | Azure AD client secret |
GRAPH_TENANT_ID | Azure AD tenant ID |
GRAPH_USER_EMAILS | Mailboxes: comma-separated list or "All" for auto-discovery |
Windows Configuration (COM Automation)
Uses native Outlook COM automation via pywin32.
{
"mcpServers": {
"outlook-email": {
"command": "C:/path/to/.venv/Scripts/python",
"args": ["C:/path/to/src/mcp_server.py"],
"env": {
"MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
"SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
"EMBEDDING_BASE_URL": "http://localhost:11434",
"EMBEDDING_MODEL": "nomic-embed-text",
"COLLECTION_NAME": "outlook-emails",
"OUTLOOK_PROVIDER": "windows",
"LOCAL_TIMEZONE": "America/Chicago"
}
}
}
}
macOS Configuration (AppleScript)
Uses AppleScript to communicate with Outlook for Mac.
{
"mcpServers": {
"outlook-email": {
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/src/mcp_server.py"],
"env": {
"MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
"SQLITE_DB_PATH": "/path/to/data/emails.db",
"EMBEDDING_BASE_URL": "http://localhost:11434",
"EMBEDDING_MODEL": "nomic-embed-text",
"COLLECTION_NAME": "outlook-emails",
"OUTLOOK_PROVIDER": "mac",
"LOCAL_TIMEZONE": "America/Los_Angeles"
}
}
}
}
Graph API Configuration (Cross-Platform)
Works on any platform with Azure AD credentials. Supports single or multiple mailboxes.
Single mailbox or specific mailboxes:
{
"mcpServers": {
"outlook-email": {
"command": "python",
"args": ["src/mcp_server.py"],
"env": {
"MONGODB_URI": "mongodb://localhost:27017/MCP",
"SQLITE_DB_PATH": "/data/emails.db",
"EMBEDDING_BASE_URL": "http://localhost:11434",
"EMBEDDING_MODEL": "nomic-embed-text",
"COLLECTION_NAME": "outlook-emails",
"OUTLOOK_PROVIDER": "graph",
"GRAPH_CLIENT_ID": "your-azure-ad-client-id",
"GRAPH_CLIENT_SECRET": "your-client-secret",
"GRAPH_TENANT_ID": "your-tenant-id",
"GRAPH_USER_EMAILS": "user1@example.com,user2@example.com"
}
}
}
}
All mailboxes in tenant (auto-discovery):
{
"mcpServers": {
"outlook-email": {
"command": "python",
"args": ["src/mcp_server.py"],
"env": {
"MONGODB_URI": "mongodb://localhost:27017/MCP",
"SQLITE_DB_PATH": "/data/emails.db",
"EMBEDDING_BASE_URL": "http://localhost:11434",
"EMBEDDING_MODEL": "nomic-embed-text",
"COLLECTION_NAME": "outlook-emails",
"OUTLOOK_PROVIDER": "graph",
"GRAPH_CLIENT_ID": "your-azure-ad-client-id",
"GRAPH_CLIENT_SECRET": "your-client-secret",
"GRAPH_TENANT_ID": "your-tenant-id",
"GRAPH_USER_EMAILS": "All"
}
}
}
}
Provider Auto-Detection
When OUTLOOK_PROVIDER is set to auto (default), the server automatically selects the best provider:
| Platform | Auto-Selected Provider |
|---|---|
| Windows | windows (COM automation) |
| macOS | mac (AppleScript) |
| Linux/Other | graph (requires Azure AD setup) |
HTTP Transport (2025-06-18 Compliant)
For HTTP transport, run the server with the --http flag:
python src/mcp_server.py --http
This will start the server at http://localhost:8000/mcp with full 2025-06-18 protocol compliance including:
- Protocol version negotiation
- Structured output schemas
- HTTP header validation
- Proper error handling
The HTTP transport supports both stateful and stateless operation modes.
Available Tools
1. process_emails
Process emails from a specified date range and return structured results:
Input:
{
"start_date": "2024-01-01", # ISO format date (YYYY-MM-DD)
"end_date": "2024-02-15", # ISO format date (YYYY-MM-DD)
"mailboxes": ["All"] # List of mailbox names or ["All"] for all mailboxes
}
Output (Structured):
{
"success": true,
"processed_count": 150,
"retrieved_count": 200,
"stored_count": 180,
"failed_count": 20,
"message": "Successfully processed 150 emails (retrieved: 200, stored: 180, failed: 20)",
"error": null
}
The tool will:
- Connect to specified Outlook mailboxes
- Retrieve emails from Inbox and Sent Items folders (and Deleted Items if enabled)
- Store emails in SQLite database
- Generate embeddings using Ollama
- Store embeddings in MongoDB for semantic search
- Return structured results with detailed statistics
Example Usage in Claude
"Process emails from February 1st to February 17th from all mailboxes"
Architecture
Provider-Based Connector Design
The server uses a provider-based abstraction for cross-platform email access:
src/connectors/
├── base.py # OutlookConnectorBase (abstract interface)
├── factory.py # create_connector() with auto-detection
├── windows_connector.py # Windows COM via pywin32
├── mac_connector.py # macOS AppleScript via osascript
└── graph_connector.py # Microsoft Graph API (cross-platform)
All connectors implement the same interface, returning standardized EmailMetadata objects regardless of platform.
Dual-Database Architecture
The server uses a hybrid storage approach:
SQLite Database:
- Primary email storage and metadata
- Full-text search capabilities
- Processing status tracking
- Date range and folder filtering
- Fast structured queries
MongoDB:
- Vector embeddings storage (768 dimensions)
- Semantic similarity search
- Metadata stored alongside embeddings
- Enables AI-powered search
Error Handling
The server provides detailed error messages for common issues:
- Invalid date formats
- Connection issues with Outlook
- MongoDB errors
- Embedding generation failures with retry logic
- SQLite storage errors
- Ollama server connection issues with automatic retries
Resource Management
The server implements proper resource management to prevent issues:
- Database connections (SQLite and MongoDB) are kept open during the server's lifetime to prevent "Cannot operate on a closed database" errors
- Connections are only closed when the server shuts down, using an atexit handler
- Destructors and context managers are used as a fallback to ensure connections are closed when objects are garbage collected
- Connection management is designed to balance resource usage with operational reliability
- Robust retry logic for external services like Ollama to handle temporary connection issues
MCP 2025-06-18 Compliance
This server has been upgraded to comply with the MCP 2025-06-18 specification:
Protocol Features
- Protocol Version: Declares
protocolVersion: "2025-06-18"during handshake - Structured Output: All tools return typed, validated Pydantic models
- HTTP Transport: Supports Streamable HTTP with proper header validation
- Tool Metadata: Enhanced tool descriptions with titles and schemas
- Error Handling: Structured error responses with detailed information
Transport Support
- STDIO: Traditional stdin/stdout communication (default)
- HTTP: Streamable HTTP on localhost:8000/mcp with header validation
- Protocol Headers: Validates MCP-Protocol-Version and Origin headers
- Single-Message JSON-RPC: No batch request support per 2025-06-18 spec
Structured Output
The process_emails tool returns a structured ProcessEmailsResult with:
success: Boolean indicating operation successprocessed_count: Number of emails successfully processedretrieved_count: Total emails retrieved from Outlookstored_count: Number of emails stored in SQLitefailed_count: Number of emails that failed processingmessage: Human-readable status messageerror: Error details if operation failed
Security Notes
- The server only processes emails from specified mailboxes
- All data is stored locally (SQLite) and in MongoDB
- No external API calls except to local Ollama server (and Microsoft Graph if using that provider)
- Requires explicit user approval for email processing
- No sensitive email data is exposed through the MCP interface
- HTTP transport binds only to localhost for security
- Graph API uses OAuth 2.0 client credentials flow with Azure AD
- Store Azure AD credentials securely (environment variables, not in code)
Debugging
If you encounter issues:
- Verify emails were successfully processed (check process_emails response)
- Ensure Ollama server is running for embedding generation
- Check that the SQLite database is accessible
- Verify MongoDB connection is working properly
- Use
check_data_consistencytool to verify SQLite/MongoDB sync
Platform-Specific Debugging
Windows:
- Ensure Outlook is running and accessible
- Check that pywin32 is installed:
pip show pywin32 - Verify COM automation works:
python -c "import win32com.client; print('OK')"
macOS:
- Ensure Outlook for Mac is installed (not just the "New Outlook" web app)
- Test AppleScript access:
osascript -e 'tell application "Microsoft Outlook" to get name' - Grant Terminal/IDE permission in System Preferences → Security & Privacy → Automation
Graph API:
- Verify Azure AD app has correct permissions (Mail.Read, User.Read.All)
- Check admin consent was granted
- Test token acquisition: credentials are logged at startup
- Verify
GRAPH_USER_EMAILSis set correctly ("All" or comma-separated emails)
Platform Limitations
| Platform | Limitation |
|---|---|
| Windows | Requires Outlook desktop app running |
| macOS | "New Outlook" may have limited AppleScript support; use Graph API as fallback |
| Graph API | Requires Azure AD setup; 30-day max date range enforced |
| All | Maximum 30-day processing range per request |
Upcoming Features
- Email summarization using LLMs
- Automatic email categorization
- Customizable email reports
- Outlook drafting email responses
- Outlook rule suggestions
- Expanded database options with Neo4j and ChromaDB integration