# 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:**
```bash
# 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:**
```bash
# Download and run the WSL test script
./test_wsl.sh
```

## Installation

### From PyPI (Recommended)

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

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

### From Source

#### Using UV

```bash
# 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

```bash
# 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):**
```json
{
  "mcpServers": {
    "outlook-windows-com": {
      "command": "outlook-mcp-server-windows-com",
      "env": {}
    }
  }
}
```

**For development/source installation:**
```json
{
  "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:**
```json
{
  "mcpServers": {
    "outlook-windows-com": {
      "command": "python",
      "args": ["-m", "outlook_mcp_server"],
      "env": {}
    }
  }
}
```

## Usage

### Running the Server

```bash
# 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

```bash
# 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:

```python
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](https://github.com/modelcontextprotocol/inspector).


You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:

```bash
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"**
```bash
# 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**
```bash
# 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