Outlook MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to Microsoft Outlook mailboxes. This server enables AI assistants and MCP clients to search, analyze, and extract insights from emails in both personal and shared mailboxes.

Features

• Multi-Mailbox Support: Access both personal inbox and shared mailboxes simultaneously

• Advanced Search Capabilities: Search emails by exact phrase matching in both subject and body

• Near-Instant Search Performance: Leverages Outlook's AdvancedSearch API for blazing-fast body searches

• Parallel Mailbox Search: Searches personal and shared mailboxes concurrently for faster results

• Full Email Content: Retrieves complete email bodies for comprehensive analysis

• Email Chain Analysis: Groups and analyzes related email conversations

• Smart Connection Management: Automatically connects to existing Outlook instances with retry logic

• Optimized Caching: Time-based cache invalidation with size limits for optimal memory usage

• Non-Blocking Operations: Async execution prevents server blocking during long operations

• Configurable Settings: Fine-tune performance and behavior through configuration file

• Cross-Folder Search: Optionally search across all folders, not just Inbox

• Automatic Fallback: Gracefully handles indexing issues with alternative search methods

Related MCP server: outlook-mcp

Requirements

• Operating System: Windows 10 or Windows 11

• Microsoft Outlook: Desktop application (not Outlook Web)

• Python: Version 3.8 or higher

• Python Packages:

  • pywin32 - For Outlook COM interface

  • mcp - MCP SDK for server implementation

Installation

1. Clone the repository:

git clone <repository-url>
cd outlook-mcp-server

2. Install dependencies:

pip install -r requirements.txt

3. Configure settings:

   • Edit src/config/config.properties with your mailbox details:

# Update this with your shared mailbox email (optional)
shared_mailbox_email=team-inbox@yourcompany.com

# Adjust search and performance settings as needed
max_search_results=50
max_body_chars=0  # 0 for full body, or limit for truncation

4. Test the connection:

python tests/test_connection.py

Configuration

The server behavior can be customized through config.properties:

Mailbox Settings

• shared_mailbox_email: Email address of shared/team mailbox (optional)

• shared_mailbox_name: Display name for the shared mailbox

Search Configuration

• max_search_results: Maximum emails to return per search (default: 50)

• max_body_chars: Maximum characters from email body (0 = unlimited)

• search_all_folders: Search all folders, not just Inbox (default: false)

Performance Settings

• max_search_body_chars: Limit for body searching during pattern matching

• connection_timeout_minutes: Outlook connection timeout

• batch_processing_size: Number of emails to process in batch

• max_connection_retries: Number of connection retry attempts (default: 3)

• max_recipients_display: Maximum recipients to show per email (default: 10)

Data Retention (Informational)

• personal_retention_months: Expected retention for personal mailbox

• shared_retention_months: Expected retention for shared mailbox

Usage

Starting the Server

1. Ensure Microsoft Outlook is running on your system

2. Start the MCP server:

python outlook_mcp.py

3. The server will start and listen for MCP client connections via stdio

Available Tools

The server provides two main tools accessible through the MCP protocol:

1. check_mailbox_access

Tests connection to Outlook and verifies access to configured mailboxes.

Parameters: None

Returns:

• Connection status

• Personal mailbox accessibility and name

• Shared mailbox accessibility and name (if configured)

• Any error messages

Example Response:

{
  "status": "success",
  "connection": {
    "outlook_connected": true,
    "timestamp": "2024-01-15T10:30:00"
  },
  "personal_mailbox": {
    "accessible": true,
    "name": "John Doe",
    "retention_months": 6
  },
  "shared_mailbox": {
    "accessible": true,
    "name": "Team Support",
    "configured": true,
    "retention_months": 12
  }
}

2. get_email_chain

Searches for emails containing specified text in both subject and body, returning complete email chains with full content.

Parameters:

• search_text (required): Exact phrase to search for

• include_personal (optional): Search personal mailbox (default: true)

• include_shared (optional): Search shared mailbox (default: true)

Returns:

• Grouped email conversations

• Full email bodies for each message

• Sender and recipient information

• Timestamps and folder locations

• Summary statistics

Example Request:

{
  "tool": "get_email_chain",
  "arguments": {
    "search_text": "server error 500",
    "include_personal": true,
    "include_shared": true
  }
}

Search Strategy

The server uses Outlook's AdvancedSearch API for near-instant search performance:

Primary Search Method: AdvancedSearch API

• Leverages Outlook's built-in search index for blazing-fast performance

• Searches both subject and body simultaneously using DASL queries

• Case-insensitive exact phrase matching using ci_phrasematch

• Near-instant results even for large mailboxes (thousands of emails)

• Asynchronous search with polling for completion (30-second timeout)

• Works identically to Outlook's UI search, providing familiar behavior

Automatic Fallback (if indexing is disabled)

If AdvancedSearch fails (rare, usually due to indexing issues):

1. Subject-only search using Restrict filters (always fast)

2. Manual iteration as last resort (limited scope)

Other Folders Search (Optional)

• Searches Sent Items and Drafts using same AdvancedSearch method

• Activated when search_all_folders=true

• Consistent performance across all folders

Performance Considerations

Search Performance

AdvancedSearch Benefits:

• 10-100x faster than traditional iteration methods

• Sub-second to few seconds response time for most searches

• Consistent performance regardless of mailbox size

• Same speed for body searches as subject searches

Parallel Search:

• Personal and shared mailboxes are searched simultaneously using threading

• ~2x faster when searching multiple mailboxes

• Proper COM initialization per thread ensures stability

Smart Connection:

• Connects to existing Outlook instance first (GetActiveObject) - instant connection

• Falls back to launching new instance only if needed

• Exponential backoff retry (1s, 2s, 4s) for resilient connection

Optimized Caching:

• 1-hour cache lifetime with automatic invalidation

• Cache size limited to 100 entries with LRU eviction

• Cache key includes search parameters for accuracy

Memory Management:

• COM references released after email extraction

• Recipients list limited to 10 by default (configurable)

• Email body truncation supported via max_body_chars

Non-Blocking Server:

• Uses asyncio.to_thread() for all Outlook operations

• Server remains responsive during long searches

• Multiple concurrent tool calls supported

max_results Behavior: The max_results configuration sets the total maximum number of emails returned across ALL mailboxes. Results are limited early during search for efficiency.

Optimization Tips

1. Ensure Outlook Indexing is Enabled:

   • Go to File → Options → Search → Indexing Options

   • Make sure Outlook is included in indexed locations

   • Allow indexing to complete for best performance

2. Use Specific Search Terms: More specific phrases yield faster, more accurate results

3. Limit Results: Set reasonable max_search_results to improve response times

4. Configure Body Limits: Use max_body_chars if full email bodies aren't needed for initial processing

5. Keep Outlook Updated: Newer versions have better search indexing and performance

Caching

The server includes built-in caching for:

• Search results (keyed by search term and mailbox selection)

• Folder references (to avoid repeated lookups)

Cache is maintained per server session and cleared on restart.

Integration with MCP Clients

This server is compatible with any MCP client that supports the stdio transport. Common integrations include:

Claude Desktop App

Add to your Claude configuration:

{
  "mcpServers": {
    "outlook": {
      "command": "python",
      "args": ["path/to/outlook_mcp.py"]
    }
  }
}

Custom MCP Clients

Connect to the server using the MCP SDK:

from mcp import Client

client = Client()
client.connect_stdio(["python", "outlook_mcp.py"])

Troubleshooting

Common Issues

"Outlook.Application" Error

• Ensure Microsoft Outlook desktop is installed (not just web access)

• Outlook must be running before starting the server

Security Dialog Appears

• This is normal on first access

• Click "Allow" to grant the server access to Outlook

• Consider enabling use_extended_mapi_login in config

Shared Mailbox Not Accessible

• Verify you have permissions to the shared mailbox

• Check the email address is correct in config.properties

• Ensure the mailbox is added to your Outlook profile

Search Returns No Results

• Verify emails exist matching your search criteria

• Try broader search terms

• Increase max_search_results if needed

• Check that Outlook has finished indexing your mailbox

Slow Search Performance

• Use more specific search terms

• Reduce max_search_results

• Consider limiting search to specific mailboxes

• Ensure Outlook is not syncing or downloading messages

Debug Mode

Enable detailed logging by setting the logging level:

import logging
logging.basicConfig(level=logging.DEBUG)

Project Structure

outlook-mcp-server/
├── outlook_mcp.py           # Main MCP server
├── requirements.txt          # Python dependencies
├── src/
│   ├── config/
│   │   ├── config_reader.py # Configuration management
│   │   └── config.properties # User settings
│   └── utils/
│       ├── outlook_client.py # Outlook COM interface
│       └── email_formatter.py # Response formatting
└── tests/
    └── test_connection.py    # Connection test utility

Architecture

Components

1. MCP Server Framework (outlook_mcp.py)

   • Implements MCP protocol specification

   • Handles tool registration and execution

   • Manages stdio communication

2. Outlook Client (src/utils/outlook_client.py)

   • COM interface to Microsoft Outlook

   • Implements search strategies

   • Manages mailbox connections

   • Handles caching

3. Email Formatter (src/utils/email_formatter.py)

   • Formats email data for AI consumption

   • Groups emails into conversations

   • Generates summaries and statistics

4. Configuration Reader (src/config/config_reader.py)

   • Loads and validates configuration

   • Provides type-safe config access

   • Supports environment variable overrides

Data Flow

1. MCP client sends tool request → MCP server

2. Server validates request parameters

3. Outlook client executes search strategy

4. Email data is extracted and formatted

5. Response is serialized and returned to client

Security Considerations

• Local Access Only: Server runs locally and accesses Outlook via COM

• Permission Prompts: Windows may show security dialogs for Outlook access

• No Credentials Stored: Uses current Windows user's Outlook profile

• Configurable Scope: Limit access to specific mailboxes via configuration

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - See LICENSE file for details

Support

For issues, questions, or suggestions:

• Open an issue on GitHub

• Check existing issues for solutions

• Provide detailed error messages and configuration (without sensitive data)

Acknowledgments

• Built on the Model Context Protocol specification

• Uses pywin32 for Windows COM interface

• Inspired by the need for AI-powered email analysis