outlook-mcp-server-windows-com 0.1.1

Microsoft Outlook MCP server for Windows using COM interface - Direct integration with local Outlook application. Supports Windows and WSL.

Outlook MCP Server - Windows COM Edition

A Model Context Protocol (MCP) server that provides AI assistants with direct access to Microsoft Outlook on Windows through COM (Component Object Model) interface. This server enables seamless integration with emails, calendar events, and contacts without requiring Azure AD credentials or Microsoft Graph API setup.

Features

🔌 Direct Outlook Integration

• Connects directly to local Outlook application using Windows COM interface
• No Azure AD registration or Graph API credentials required
• Works with existing Outlook installations and profiles

📧 Email Management

• Get emails from any folder (Inbox, Sent Items, Drafts, etc.)
• Send emails with support for CC, BCC, and rich formatting
• Search and filter emails with pagination support
• Read email details including sender, recipients, attachments

📅 Calendar Operations

• View calendar events with date range filtering
• Create new appointments with attendees and locations
• Support for recurring events and all-day events
• Access multiple calendars and calendar folders

👥 Contact Management

• Browse contacts from Outlook address book
• Create new contacts with full contact information
• Access contact details including multiple email addresses and phone numbers
• Company and job title information

🔧 MCP Tools

• get-emails - Retrieve emails from specified folders
• send-email - Send emails with full formatting support
• get-calendar-events - Get upcoming calendar events
• create-calendar-event - Create new calendar appointments
• get-contacts - Browse contact directory
• create-contact - Add new contacts

📝 MCP Prompts

• summarize-emails - Generate email summaries
• schedule-summary - Create calendar overviews
• compose-email - Assist with professional email composition

Prerequisites

Windows Requirements

• Windows OS (Windows 10/11 recommended)
• Microsoft Outlook installed and configured
• Python 3.8+ with pip or uv package manager

Platform Support

• ✅ Windows: Full functionality with COM interface
• ✅ WSL (Windows Subsystem for Linux): Full functionality with additional setup
• ⚠️ macOS/Linux: Limited functionality (server will start but cannot connect to Outlook)

WSL (Windows Subsystem for Linux) Support

The server works in WSL environments with proper configuration:

Requirements:

• WSL 1 or WSL 2 on Windows 10/11
• Outlook running on the Windows host
• Python 3.8+ in WSL
• pywin32 package installed in WSL

Installation in WSL:

# Install with WSL support
pip install outlook-mcp-server-windows-com[wsl]

# Or install pywin32 separately
pip install outlook-mcp-server-windows-com
pip install pywin32

Testing WSL Setup:

# Download and run the WSL test script
./test_wsl.sh

Installation

From PyPI (Recommended)

# Install from PyPI
pip install outlook-mcp-server-windows-com

# Or using UV
uv add outlook-mcp-server-windows-com

From Source

Using UV

# Clone the repository
git clone <repository-url> outlook-mcp-server-windows-com
cd outlook-mcp-server-windows-com

# Install dependencies with UV
uv sync

Using Pip

# Clone the repository
git clone <repository-url> outlook-mcp-server-windows-com
cd outlook-mcp-server-windows-com

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # On Windows
# source venv/bin/activate  # On macOS/Linux

# Install dependencies
pip install -e .

Quickstart

Install

Claude Desktop

Add this to your Claude Desktop configuration file (%APPDATA%\Claude\claude_desktop_config.json on Windows):

For published package (recommended):

{
  "mcpServers": {
    "outlook-windows-com": {
      "command": "outlook-mcp-server-windows-com",
      "env": {}
    }
  }
}

For development/source installation:

{
  "mcpServers": {
    "outlook-windows-com": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\outlook-mcp-server-windows-com", "run", "python", "-m", "outlook_mcp_server"],
      "env": {}
    }
  }
}

Using system Python:

{
  "mcpServers": {
    "outlook-windows-com": {
      "command": "python",
      "args": ["-m", "outlook_mcp_server"],
      "env": {}
    }
  }
}

Usage

Running the Server

# If installed from PyPI
outlook-mcp-server-windows-com

# Or using Python module
python -m outlook_mcp_server

# From source with UV
uv run python -m outlook_mcp_server

Claude Desktop Integration

Development

Project Structure

outlook-mcp-server-windows-com/
├── src/
│   └── outlook_mcp_server/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── .vscode/                   # VS Code configuration
│   ├── launch.json           # Debug configurations
│   └── settings.json         # Editor settings
├── pyproject.toml            # Project configuration
├── LICENSE                   # MIT license
├── MANIFEST.in              # Package distribution files
├── README.md                # This file
├── test_client.py           # Cross-platform test script
├── test_wsl.sh             # WSL-specific test script
├── test_windows.ps1        # Windows PowerShell test script
└── uv.lock                 # Dependency lock file

Testing

# Test server functionality (all platforms)
python test_client.py

# Or test directly with UV
uv run python test_client.py

# WSL-specific comprehensive test
./test_wsl.sh  # Only in WSL environment

# Test Windows COM access manually
python -c "import win32com.client; print('✅ COM available')"

Platform Detection

The server includes automatic platform detection:

import platform

if platform.system() == "Windows":
    try:
        import win32com.client
        WINDOWS_COM_AVAILABLE = True
    except ImportError:
        WINDOWS_COM_AVAILABLE = False
else:
    WINDOWS_COM_AVAILABLE = False

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /path/to/outlook-mcp-server-windows-com run python -m outlook_mcp_server

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

Troubleshooting

Windows Issues

"Failed to connect to Outlook"

• Ensure Outlook is running and properly configured
• Check that your Outlook profile is set up correctly
• Try restarting Outlook and the MCP server
• Run Outlook as administrator if needed

"Windows COM interface not available"

• Install pywin32: pip install pywin32
• Restart your command prompt/terminal after installation

WSL Issues

"pywin32 not available in WSL"

# Install pywin32 in WSL
pip install pywin32

# Or install with WSL extras
pip install outlook-mcp-server-windows-com[wsl]

"Failed to connect to Outlook from WSL"

• Ensure Outlook is running on the Windows host (not in WSL)
• Try running Outlook as administrator on Windows
• Check that WSL has proper Windows integration enabled
• Verify Windows Defender/antivirus isn't blocking COM access

WSL COM Access Issues

• Some WSL configurations may block COM access
• Try running the test script: ./test_wsl.sh
• Consider using WSL 2 for better Windows integration
• Ensure your WSL distribution is up to date

Testing WSL Environment

# Run comprehensive WSL test
./test_wsl.sh

# Manual test of COM access
python3 -c "import win32com.client; print('COM available')"

General Issues

"Import errors in IDE"

• Import errors for MCP libraries are normal in development
• The server will work correctly when run in the proper environment

Permission Errors

• Try running your terminal/command prompt as administrator
• Check that Outlook isn't in "safe mode"
• Verify your user has proper permissions to access Outlook