# 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
Raw data
{
"_id": null,
"home_page": null,
"name": "outlook-mcp-server-windows-com",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "calendar, com, contacts, email, mcp, microsoft, outlook, windows, wsl",
"author": null,
"author_email": "akhilthomas236 <akhilthomas236@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e4/bb/3fc599cb06c053d80b907fb63977e0a5676871d4c072ebf17f65cf4f8e57/outlook_mcp_server_windows_com-0.1.1.tar.gz",
"platform": null,
"description": "# Outlook MCP Server - Windows COM Edition\n\nA 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.\n\n## Features\n\n### \ud83d\udd0c **Direct Outlook Integration**\n- Connects directly to local Outlook application using Windows COM interface\n- No Azure AD registration or Graph API credentials required\n- Works with existing Outlook installations and profiles\n\n### \ud83d\udce7 **Email Management**\n- **Get emails** from any folder (Inbox, Sent Items, Drafts, etc.)\n- **Send emails** with support for CC, BCC, and rich formatting\n- **Search and filter** emails with pagination support\n- **Read email details** including sender, recipients, attachments\n\n### \ud83d\udcc5 **Calendar Operations**\n- **View calendar events** with date range filtering\n- **Create new appointments** with attendees and locations\n- **Support for recurring events** and all-day events\n- **Access multiple calendars** and calendar folders\n\n### \ud83d\udc65 **Contact Management**\n- **Browse contacts** from Outlook address book\n- **Create new contacts** with full contact information\n- **Access contact details** including multiple email addresses and phone numbers\n- **Company and job title information**\n\n### \ud83d\udd27 **MCP Tools**\n- `get-emails` - Retrieve emails from specified folders\n- `send-email` - Send emails with full formatting support\n- `get-calendar-events` - Get upcoming calendar events\n- `create-calendar-event` - Create new calendar appointments\n- `get-contacts` - Browse contact directory\n- `create-contact` - Add new contacts\n\n### \ud83d\udcdd **MCP Prompts**\n- `summarize-emails` - Generate email summaries\n- `schedule-summary` - Create calendar overviews\n- `compose-email` - Assist with professional email composition\n\n## Prerequisites\n\n### Windows Requirements\n- **Windows OS** (Windows 10/11 recommended)\n- **Microsoft Outlook** installed and configured\n- **Python 3.8+** with pip or uv package manager\n\n### Platform Support\n- \u2705 **Windows**: Full functionality with COM interface\n- \u2705 **WSL (Windows Subsystem for Linux)**: Full functionality with additional setup\n- \u26a0\ufe0f **macOS/Linux**: Limited functionality (server will start but cannot connect to Outlook)\n\n### WSL (Windows Subsystem for Linux) Support\nThe server works in WSL environments with proper configuration:\n\n**Requirements:**\n- WSL 1 or WSL 2 on Windows 10/11\n- Outlook running on the Windows host\n- Python 3.8+ in WSL\n- pywin32 package installed in WSL\n\n**Installation in WSL:**\n```bash\n# Install with WSL support\npip install outlook-mcp-server-windows-com[wsl]\n\n# Or install pywin32 separately\npip install outlook-mcp-server-windows-com\npip install pywin32\n```\n\n**Testing WSL Setup:**\n```bash\n# Download and run the WSL test script\n./test_wsl.sh\n```\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Install from PyPI\npip install outlook-mcp-server-windows-com\n\n# Or using UV\nuv add outlook-mcp-server-windows-com\n```\n\n### From Source\n\n#### Using UV\n\n```bash\n# Clone the repository\ngit clone <repository-url> outlook-mcp-server-windows-com\ncd outlook-mcp-server-windows-com\n\n# Install dependencies with UV\nuv sync\n```\n\n#### Using Pip\n\n```bash\n# Clone the repository\ngit clone <repository-url> outlook-mcp-server-windows-com\ncd outlook-mcp-server-windows-com\n\n# Create virtual environment\npython -m venv venv\nvenv\\Scripts\\activate # On Windows\n# source venv/bin/activate # On macOS/Linux\n\n# Install dependencies\npip install -e .\n```\n\n## Quickstart\n\n### Install\n\n#### Claude Desktop\n\nAdd this to your Claude Desktop configuration file (`%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n**For published package (recommended):**\n```json\n{\n \"mcpServers\": {\n \"outlook-windows-com\": {\n \"command\": \"outlook-mcp-server-windows-com\",\n \"env\": {}\n }\n }\n}\n```\n\n**For development/source installation:**\n```json\n{\n \"mcpServers\": {\n \"outlook-windows-com\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"C:\\\\path\\\\to\\\\outlook-mcp-server-windows-com\", \"run\", \"python\", \"-m\", \"outlook_mcp_server\"],\n \"env\": {}\n }\n }\n}\n```\n\n**Using system Python:**\n```json\n{\n \"mcpServers\": {\n \"outlook-windows-com\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"outlook_mcp_server\"],\n \"env\": {}\n }\n }\n}\n```\n\n## Usage\n\n### Running the Server\n\n```bash\n# If installed from PyPI\noutlook-mcp-server-windows-com\n\n# Or using Python module\npython -m outlook_mcp_server\n\n# From source with UV\nuv run python -m outlook_mcp_server\n```\n\n### Claude Desktop Integration\n\n## Development\n\n### Project Structure\n```\noutlook-mcp-server-windows-com/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 outlook_mcp_server/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 server.py # Main MCP server implementation\n\u251c\u2500\u2500 .vscode/ # VS Code configuration\n\u2502 \u251c\u2500\u2500 launch.json # Debug configurations\n\u2502 \u2514\u2500\u2500 settings.json # Editor settings\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 LICENSE # MIT license\n\u251c\u2500\u2500 MANIFEST.in # Package distribution files\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 test_client.py # Cross-platform test script\n\u251c\u2500\u2500 test_wsl.sh # WSL-specific test script\n\u251c\u2500\u2500 test_windows.ps1 # Windows PowerShell test script\n\u2514\u2500\u2500 uv.lock # Dependency lock file\n```\n\n### Testing\n\n```bash\n# Test server functionality (all platforms)\npython test_client.py\n\n# Or test directly with UV\nuv run python test_client.py\n\n# WSL-specific comprehensive test\n./test_wsl.sh # Only in WSL environment\n\n# Test Windows COM access manually\npython -c \"import win32com.client; print('\u2705 COM available')\"\n```\n\n### Platform Detection\nThe server includes automatic platform detection:\n\n```python\nimport platform\n\nif platform.system() == \"Windows\":\n try:\n import win32com.client\n WINDOWS_COM_AVAILABLE = True\n except ImportError:\n WINDOWS_COM_AVAILABLE = False\nelse:\n WINDOWS_COM_AVAILABLE = False\n```\n\n### Debugging\n\nSince MCP servers run over stdio, debugging can be challenging. For the best debugging\nexperience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).\n\n\nYou can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:\n\n```bash\nnpx @modelcontextprotocol/inspector uv --directory /path/to/outlook-mcp-server-windows-com run python -m outlook_mcp_server\n```\n\n\nUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.\n\n## Troubleshooting\n\n### Windows Issues\n\n**\"Failed to connect to Outlook\"**\n- Ensure Outlook is running and properly configured\n- Check that your Outlook profile is set up correctly\n- Try restarting Outlook and the MCP server\n- Run Outlook as administrator if needed\n\n**\"Windows COM interface not available\"**\n- Install pywin32: `pip install pywin32`\n- Restart your command prompt/terminal after installation\n\n### WSL Issues\n\n**\"pywin32 not available in WSL\"**\n```bash\n# Install pywin32 in WSL\npip install pywin32\n\n# Or install with WSL extras\npip install outlook-mcp-server-windows-com[wsl]\n```\n\n**\"Failed to connect to Outlook from WSL\"**\n- Ensure Outlook is running on the Windows host (not in WSL)\n- Try running Outlook as administrator on Windows\n- Check that WSL has proper Windows integration enabled\n- Verify Windows Defender/antivirus isn't blocking COM access\n\n**WSL COM Access Issues**\n- Some WSL configurations may block COM access\n- Try running the test script: `./test_wsl.sh`\n- Consider using WSL 2 for better Windows integration\n- Ensure your WSL distribution is up to date\n\n**Testing WSL Environment**\n```bash\n# Run comprehensive WSL test\n./test_wsl.sh\n\n# Manual test of COM access\npython3 -c \"import win32com.client; print('COM available')\"\n```\n\n### General Issues\n\n**\"Import errors in IDE\"**\n- Import errors for MCP libraries are normal in development\n- The server will work correctly when run in the proper environment\n\n**Permission Errors**\n- Try running your terminal/command prompt as administrator\n- Check that Outlook isn't in \"safe mode\"\n- Verify your user has proper permissions to access Outlook",
"bugtrack_url": null,
"license": "MIT",
"summary": "Microsoft Outlook MCP server for Windows using COM interface - Direct integration with local Outlook application. Supports Windows and WSL.",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/akhilthomas236/outlook-mcp-server-windows-com#readme",
"Homepage": "https://github.com/akhilthomas236/outlook-mcp-server-windows-com",
"Issues": "https://github.com/akhilthomas236/outlook-mcp-server-windows-com/issues",
"Repository": "https://github.com/akhilthomas236/outlook-mcp-server-windows-com"
},
"split_keywords": [
"calendar",
" com",
" contacts",
" email",
" mcp",
" microsoft",
" outlook",
" windows",
" wsl"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "980efc6437fe866f810a837d2e531b7859979f6d8a5b1ef5bc01853c6108e8f6",
"md5": "7c1aff76228c3e6e271dcb7d97e635e5",
"sha256": "3a26064f8afe36edc347280707f7f5b65113b1e484477f15d1bc5e0542412328"
},
"downloads": -1,
"filename": "outlook_mcp_server_windows_com-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c1aff76228c3e6e271dcb7d97e635e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13861,
"upload_time": "2025-07-19T12:51:03",
"upload_time_iso_8601": "2025-07-19T12:51:03.892813Z",
"url": "https://files.pythonhosted.org/packages/98/0e/fc6437fe866f810a837d2e531b7859979f6d8a5b1ef5bc01853c6108e8f6/outlook_mcp_server_windows_com-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e4bb3fc599cb06c053d80b907fb63977e0a5676871d4c072ebf17f65cf4f8e57",
"md5": "1dd2533a98418be1141079f8028efcfe",
"sha256": "27767892414caea9e434e76dd31893c461a9dbcd97d887b714a36fc9b7805922"
},
"downloads": -1,
"filename": "outlook_mcp_server_windows_com-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1dd2533a98418be1141079f8028efcfe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 39981,
"upload_time": "2025-07-19T12:51:04",
"upload_time_iso_8601": "2025-07-19T12:51:04.924888Z",
"url": "https://files.pythonhosted.org/packages/e4/bb/3fc599cb06c053d80b907fb63977e0a5676871d4c072ebf17f65cf4f8e57/outlook_mcp_server_windows_com-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 12:51:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "akhilthomas236",
"github_project": "outlook-mcp-server-windows-com#readme",
"github_not_found": true,
"lcname": "outlook-mcp-server-windows-com"
}
JSON
