Outlook-MCP-Server by Abhishek-Aditya-bs - MCP Server

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

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

Clone the repository:

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

Install dependencies:

pip install -r requirements.txt

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

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

Ensure Microsoft Outlook is running on your system
Start the MCP server:

python outlook_mcp.py

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

Subject-only search using Restrict filters (always fast)
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

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
Use Specific Search Terms: More specific phrases yield faster, more accurate results
Limit Results: Set reasonable max_search_results to improve response times
Configure Body Limits: Use max_body_chars if full email bodies aren't needed for initial processing
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

MCP Server Framework (outlook_mcp.py)
- Implements MCP protocol specification
- Handles tool registration and execution
- Manages stdio communication
Outlook Client (src/utils/outlook_client.py)
- COM interface to Microsoft Outlook
- Implements search strategies
- Manages mailbox connections
- Handles caching
Email Formatter (src/utils/email_formatter.py)
- Formats email data for AI consumption
- Groups emails into conversations
- Generates summaries and statistics
Configuration Reader (src/config/config_reader.py)
- Loads and validates configuration
- Provides type-safe config access
- Supports environment variable overrides

Data Flow

MCP client sends tool request → MCP server
Server validates request parameters
Outlook client executes search strategy
Email data is extracted and formatted
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:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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

Abhishek-Aditya-bs/Outlook-MCP-Server