Outlook Email Processor

by cam10001110101

14 stars

370 downloads

Not rated

GitHub

About

Integrates with Outlook to provide email processing, semantic search, and metadata storage capabilities using MongoDB and SQLite, enabling advanced analysis and retrieval of email data in Windows environments.

Details

Author: cam10001110101
Repository: Cam10001110101/mcp-server-outlook-email
GitHub stars: 14
Downloads: 370
Categories: Communication, Automation, Other, Productivity, Developer Tools, Design, File Management, AI, Search, Database, Frontend, Community
Tags: #integration, #mongodb, #sqlite

- 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

- 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

- 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

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Outlook Email Processor

Command (node, npx, python, etc.) /path/to/.venv/bin/python
Arguments
- Argument 1 /path/to/src/mcp_server.py
Environment
- MONGODB_URI mongodb://localhost:27017/MCP?authSource=admin
- LOCAL_TIMEZONE America/Los_Angeles
- SQLITE_DB_PATH /path/to/data/emails.db
- COLLECTION_NAME outlook-emails
- EMBEDDING_MODEL nomic-embed-text
- OUTLOOK_PROVIDER mac
- EMBEDDING_BASE_URL http://localhost:11434
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Los_Angeles",
                "SQLITE_DB_PATH": "/path/to/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "mac",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "/path/to/src/mcp_server.py"
            ],
            "command": "/path/to/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Chicago",
                "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "windows",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "C:/path/to/src/mcp_server.py"
            ],
            "command": "C:/path/to/.venv/Scripts/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP",
                "SQLITE_DB_PATH": "/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
                "GRAPH_TENANT_ID": "your-tenant-id",
                "OUTLOOK_PROVIDER": "graph",
                "GRAPH_USER_EMAILS": "user1@example.com,user2@example.com",
                "EMBEDDING_BASE_URL": "http://localhost:11434",
                "GRAPH_CLIENT_SECRET": "your-client-secret"
            },
            "args": [
                "src/mcp_server.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Los_Angeles",
                "SQLITE_DB_PATH": "/path/to/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "mac",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "/path/to/src/mcp_server.py"
            ],
            "command": "/path/to/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Chicago",
                "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "windows",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "C:/path/to/src/mcp_server.py"
            ],
            "command": "C:/path/to/.venv/Scripts/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP",
                "SQLITE_DB_PATH": "/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
                "GRAPH_TENANT_ID": "your-tenant-id",
                "OUTLOOK_PROVIDER": "graph",
                "GRAPH_USER_EMAILS": "user1@example.com,user2@example.com",
                "EMBEDDING_BASE_URL": "http://localhost:11434",
                "GRAPH_CLIENT_SECRET": "your-client-secret"
            },
            "args": [
                "src/mcp_server.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Los_Angeles",
                "SQLITE_DB_PATH": "/path/to/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "mac",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "/path/to/src/mcp_server.py"
            ],
            "command": "/path/to/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Chicago",
                "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "windows",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "C:/path/to/src/mcp_server.py"
            ],
            "command": "C:/path/to/.venv/Scripts/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP",
                "SQLITE_DB_PATH": "/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
                "GRAPH_TENANT_ID": "your-tenant-id",
                "OUTLOOK_PROVIDER": "graph",
                "GRAPH_USER_EMAILS": "user1@example.com,user2@example.com",
                "EMBEDDING_BASE_URL": "http://localhost:11434",
                "GRAPH_CLIENT_SECRET": "your-client-secret"
            },
            "args": [
                "src/mcp_server.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Los_Angeles",
                "SQLITE_DB_PATH": "/path/to/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "mac",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "/path/to/src/mcp_server.py"
            ],
            "command": "/path/to/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Chicago",
                "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "windows",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "C:/path/to/src/mcp_server.py"
            ],
            "command": "C:/path/to/.venv/Scripts/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP",
                "SQLITE_DB_PATH": "/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
                "GRAPH_TENANT_ID": "your-tenant-id",
                "OUTLOOK_PROVIDER": "graph",
                "GRAPH_USER_EMAILS": "user1@example.com,user2@example.com",
                "EMBEDDING_BASE_URL": "http://localhost:11434",
                "GRAPH_CLIENT_SECRET": "your-client-secret"
            },
            "args": [
                "src/mcp_server.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Los_Angeles",
                "SQLITE_DB_PATH": "/path/to/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "mac",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "/path/to/src/mcp_server.py"
            ],
            "command": "/path/to/.venv/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Chicago",
                "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "windows",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "C:/path/to/src/mcp_server.py"
            ],
            "command": "C:/path/to/.venv/Scripts/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP",
                "SQLITE_DB_PATH": "/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
                "GRAPH_TENANT_ID": "your-tenant-id",
                "OUTLOOK_PROVIDER": "graph",
                "GRAPH_USER_EMAILS": "user1@example.com,user2@example.com",
                "EMBEDDING_BASE_URL": "http://localhost:11434",
                "GRAPH_CLIENT_SECRET": "your-client-secret"
            },
            "args": [
                "src/mcp_server.py"
            ],
            "command": "python"
        }
    }
}

From the repository

2 Create And Activate Virtual Environment

uv venv .venv # Windows .venv\Scripts\activate # macOS/Linux source .venv/bin/activate

# 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]"

Graph Api Configuration Cross Platform

Works on any platform with Azure AD credentials. Supports single or multiple 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" } } } }

WhenOUTLOOK_PROVIDERis set toauto(default), the server automatically selects the best provider:

For HTTP transport, run the server with the--httpflag:

This will start the server athttp://localhost:8000/mcpwith 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.

Process emails from a specified date range and return structured results:

{ "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 }

{ "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 }

- 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

"Process emails from February 1st to February 17th from all mailboxes"

The server uses aprovider-based abstractionfor 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 standardizedEmailMetadataobjects regardless of platform.

The server uses a hybrid storage approach:

- Primary email storage and metadata
- Full-text search capabilities
- Processing status tracking
- Date range and folder filtering
- Fast structured queries

- Vector embeddings storage (768 dimensions)
- Semantic similarity search
- Metadata stored alongside embeddings
- Enables AI-powered search

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

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

This server has been upgraded to comply with the MCP 2025-06-18 specification:

- Protocol Version: DeclaresprotocolVersion: "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

- 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

Theprocess_emailstool returns a structuredProcessEmailsResultwith:

- success: Boolean indicating operation success
- processed_count: Number of emails successfully processed
- retrieved_count: Total emails retrieved from Outlook
- stored_count: Number of emails stored in SQLite
- failed_count: Number of emails that failed processing
- message: Human-readable status message
- error: Error details if operation failed

- 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)
- 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
- Usecheck_data_consistencytool to verify SQLite/MongoDB sync

- 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')"

- 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

- 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
- VerifyGRAPH_USER_EMAILSis set correctly ("All" or comma-separated emails)

Fast MCP server for Apple Mail with batch JXA (87x faster) and FTS5 search index (700-3500x faster).

Email management via IMAP/SMTP, multi-account

Read, organise and send from the IMAP email accounts you already have. Nothing sends without your approval.

A seamless email management interface powered by Claude.

Automate email tasks using SMTP and IMAP protocols.

Local email connectivity for AI agents — read, draft, send, and organize Outlook mail via MCP. Apache-2.0 licensed.

Read, search, and manage emails from your inbox, including downloading attachments and listing folders.

Interact with Fastmail email, contacts, and calendar data using the Fastmail API.

Integrate your Fastmail account with AI assistants using the Model Context Protocol.

Query live Gmail data using LLMs via CData's read-only MCP server.

`process_emails`

Process emails from a specified date range and return structured results. Input: start_date (string, ISO format), end_date (string, ISO format), mailboxes (list of strings or ['All']). Output: success (boolean), processed_count (integer), retrieved_count (integer), stored_count (integer), failed_count (integer), message (string), error (string).

`search_emails`

Search for emails based on specified criteria. Input: query (string), filters (optional). Output: list of matching emails.

`analyze_email_sentiment`

Analyze the sentiment of specified emails. Input: email_ids (list of strings). Output: sentiment scores (dictionary with email IDs and their respective sentiment scores).

`find_actionable_items`

Identify actionable items from a list of emails. Input: email_ids (list of strings). Output: list of actionable items.

`export_email_data`

Export email data to specified formats (CSV, JSON, HTML, Excel). Input: format (string), email_ids (list of strings). Output: success (boolean), message (string).

`list_outlook_folders`

List all available Outlook folders. Output: list of folder names.

`get_folder_statistics`

Get statistics for specified Outlook folders. Input: folder_names (list of strings). Output: statistics (dictionary with folder names and their respective statistics).

`organize_emails_by_rules`

Organize emails based on specified rules. Input: rules (dictionary), email_ids (list of strings). Output: success (boolean), message (string).

`extract_contacts`

Extract contacts from processed emails. Output: list of contacts.

`get_email_statistics`

Retrieve statistics regarding processed emails. Output: statistics (dictionary with various email processing metrics).

`check_data_consistency`

Check the consistency of data between SQLite and MongoDB. Output: consistency status (boolean), discrepancies (list of discrepancies if any).

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "outlook email processor": {
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
                "LOCAL_TIMEZONE": "America/Los_Angeles",
                "SQLITE_DB_PATH": "/path/to/data/emails.db",
                "COLLECTION_NAME": "outlook-emails",
                "EMBEDDING_MODEL": "nomic-embed-text",
                "OUTLOOK_PROVIDER": "mac",
                "EMBEDDING_BASE_URL": "http://localhost:11434"
            },
            "args": [
                "/path/to/src/mcp_server.py"
            ],
            "command": "/path/to/.venv/bin/python"
        }
    }
}

Linux

{
    "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP",
        "SQLITE_DB_PATH": "/data/emails.db",
        "COLLECTION_NAME": "outlook-emails",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
        "GRAPH_TENANT_ID": "your-tenant-id",
        "OUTLOOK_PROVIDER": "graph",
        "GRAPH_USER_EMAILS": "user1@example.com,user2@example.com",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "GRAPH_CLIENT_SECRET": "your-client-secret"
    },
    "args": [
        "src/mcp_server.py"
    ],
    "command": "python"
}

Macos

{
    "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "LOCAL_TIMEZONE": "America/Los_Angeles",
        "SQLITE_DB_PATH": "/path/to/data/emails.db",
        "COLLECTION_NAME": "outlook-emails",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "OUTLOOK_PROVIDER": "mac",
        "EMBEDDING_BASE_URL": "http://localhost:11434"
    },
    "args": [
        "/path/to/src/mcp_server.py"
    ],
    "command": "/path/to/.venv/bin/python"
}

Windows

{
    "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "LOCAL_TIMEZONE": "America/Chicago",
        "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
        "COLLECTION_NAME": "outlook-emails",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "OUTLOOK_PROVIDER": "windows",
        "EMBEDDING_BASE_URL": "http://localhost:11434"
    },
    "args": [
        "C:/path/to/src/mcp_server.py"
    ],
    "command": "C:/path/to/.venv/Scripts/python"
}

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-text model - 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:

1. Go to Azure Portal → Azure Active Directory → App registrations
2. Click "New registration"
3. Name your app and select "Accounts in this organizational directory only"
4. After creation, note the Application (client) ID and Directory (tenant) ID
5. Go to "Certificates & secrets" → "New client secret" → note the secret value
6. Go to "API permissions" → "Add a permission" → "Microsoft Graph" → "Application permissions"
7. Add: Mail.Read, User.Read.All (for multi-account discovery)
8. 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

…

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

2 Create And Activate Virtual Environment

Graph Api Configuration Cross Platform

process_emails

search_emails

analyze_email_sentiment

find_actionable_items

export_email_data

list_outlook_folders

get_folder_statistics

organize_emails_by_rules

extract_contacts

get_email_statistics

check_data_consistency

Claude Desktop / Cursor

Linux

Macos

Windows

Email Processing MCP Server

Features

Core Capabilities

Cross-Platform Support

MCP 2025-06-18 Compliance

Available Tools (12+)

Prerequisites

Required (All Platforms)

Platform-Specific Requirements

Installation

1. Install uv (if not already installed)

2. Create and activate virtual environment

Windows

macOS/Linux

3. Install dependencies

Graph API support (cross-platform cloud access)

All optional dependencies

4. Install Ollama embedding model

5. (Graph API only) Register Azure AD Application

Configuration

Environment Variables

Windows Configuration (COM Automation)

macOS Configuration (AppleScript)

Graph API Configuration (Cross-Platform)

Provider Auto-Detection

Install

More like this

@mendableai/firecrawl Mcp Server

Umut Naci

Playwright

Sequential Thinking

Slack

Filesystem

`process_emails`

`search_emails`

`analyze_email_sentiment`

`find_actionable_items`

`export_email_data`

`list_outlook_folders`

`get_folder_statistics`

`organize_emails_by_rules`

`extract_contacts`

`get_email_statistics`

`check_data_consistency`