# 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
- ⚠️ **macOS/Linux**: Limited functionality (server will start but cannot connect to Outlook)

## Installation

### Using UV (Recommended)

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

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

Or if using system Python:

```json
{
  "mcpServers": {
    "outlook-windows-com": {
      "command": "python",
      "args": ["-m", "outlook_mcp_server.server"],
      "cwd": "C:\\path\\to\\outlook-mcp-server-windows-com\\src",
      "env": {}
    }
  }
}
```

## Usage

### Running the Server

```bash
# Using UV
uv run python -m outlook_mcp_server

# Or directly with Python
python -m outlook_mcp_server.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
├── README.md                 # This file
├── test_client.py            # Test script
└── uv.lock                   # Dependency lock file
```

### Testing

```bash
# Test server functionality
python test_client.py

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

### 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.