MCP Outlook
by Vince1024
README.md
# MCP Outlook
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://www.microsoft.com/windows)
[](https://modelcontextprotocol.io)
<img src="https://api.iconify.design/material-symbols/mail-outline.svg?color=%23004080" width="60"> <img src="https://api.iconify.design/material-symbols/calendar-month-outline.svg?color=%23004080" width="60"> <img src="https://api.iconify.design/material-symbols/perm-contact-calendar.svg?color=%23004080" width="60"> <img src="https://api.iconify.design/material-symbols/folder-outline.svg?color=%23004080" width="60"> <img src="https://api.iconify.design/material-symbols/settings-account-box.svg?color=%23004080" width="60">
A Model Context Protocol (MCP) server for Microsoft Outlook integration.
**Version**: 1.0.3 | **Documentation**: [DOCUMENTATION.md](DOCUMENTATION.md) | **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md) | **Examples**: [EXAMPLES.md](EXAMPLES.md)
## Overview
This MCP server provides AI assistants with the ability to interact with Microsoft Outlook, including:
- <img src="https://api.iconify.design/material-symbols/mail-outline.svg?color=%23004080" width="20"> **Email Management**: Read, search, send, and draft emails with HTML support and Outlook signatures
- <img src="https://api.iconify.design/material-symbols/attach-file.svg?color=%23004080" width="20"> **Attachment Management**: List, download, and send email attachments with robust detection
- <img src="https://api.iconify.design/material-symbols/calendar-month-outline.svg?color=%23004080" width="20"> **Calendar Management**: View, create, and search calendar events
- <img src="https://api.iconify.design/material-symbols/perm-contact-calendar.svg?color=%23004080" width="20"> **Contact Management**: View, create, and search contacts
- <img src="https://api.iconify.design/material-symbols/folder-outline.svg?color=%23004080" width="20"> **Folder Management**: List folders, search in custom folders, and view Outlook rules
- <img src="https://api.iconify.design/material-symbols/settings-account-box.svg?color=%23004080" width="20"> **Auto-Learning Style**: Automatically learns your email formatting preferences (font, size, color) from sent emails
## Features
> **Detailed documentation for each feature**: [DOCUMENTATION.md](DOCUMENTATION.md)
### <img src="https://api.iconify.design/material-symbols/mail-outline.svg?color=%23004080" width="30"> 5 Email Tools ([Documentation](DOCUMENTATION.md#email-tools))
- `get_inbox_emails` - Retrieve emails from inbox with filtering options
- `get_sent_emails` - Retrieve sent emails
- `search_emails` - Search emails across folders by subject, body, or sender
- `send_email` - Send emails with CC/BCC support, HTML content, and **auto-learned style**
- `create_draft_email` - Create draft emails without sending, with HTML and **auto-learned style**
> **Auto-Learning Style**: When `OUTLOOK_AUTO_LEARN_STYLE=true`, the server dynamically learns your email formatting style (font-family, font-size, color) from your most recent sent email each time you send or create a draft. This learned style is automatically applied to plain-text emails. No caching - learning happens live on every send/draft operation.
### <img src="https://api.iconify.design/material-symbols/attach-file.svg?color=%23004080" width="30"> 3 Attachment Tools ([Documentation](DOCUMENTATION.md#attachment-tools))
- `get_email_attachments` - List all attachments from an email (with robust detection)
- `download_email_attachment` - Download a specific attachment to disk
- `send_email_with_attachments` - Send emails with file attachments
> **Robust Detection**: Attachment detection intelligently filters out inline images, email signatures, and embedded items to show only real file attachments. Uses ContentID detection, file size filtering, and type checking.
### <img src="https://api.iconify.design/material-symbols/calendar-month-outline.svg?color=%23004080" width="30"> 3 Calendar Tools ([Documentation](DOCUMENTATION.md#calendar-tools))
- `get_calendar_events` - Get upcoming calendar events
- `create_calendar_event` - Create new calendar events with attendees
- `search_calendar_events` - Search events by subject or location
### <img src="https://api.iconify.design/material-symbols/perm-contact-calendar.svg?color=%23004080" width="30"> 3 Contact Tools ([Documentation](DOCUMENTATION.md#contact-tools))
- `get_contacts` - Retrieve contacts with optional name filtering
- `create_contact` - Create new contacts
- `search_contacts` - Search contacts by name, email, or company
### <img src="https://api.iconify.design/material-symbols/folder-outline.svg?color=%23004080" width="30"> 3 Folder Tools ([Documentation](DOCUMENTATION.md#folder-tools))
- `list_outlook_folders` - List all Outlook folders (ultra-fast, no item counts)
- `search_emails_in_custom_folder` - Search in specific custom folders with date filtering
- `list_outlook_rules` - List all Outlook rules with conditions and actions
## Performance Optimizations
This MCP has been heavily optimized for **large mailboxes** and to **minimize Outlook freezing**:
- **Folder caching** - 45x faster on repeated searches
- **Date filtering** - Search only recent emails (default: 2 days)
- **Direct indexing** - Faster iteration without `items.Count`
- **Reduced limits** - Prevents long freezes (max 50 emails)
- **Smart defaults** - Optimized for daily usage
- **Silent logging** - Minimal log output for cleaner integration
**See [DOCUMENTATION.md - Performances](DOCUMENTATION.md#performances) for detailed performance information.**
## Installation
> **Quick Start Guide**: [QUICK_START.md](QUICK_START.md) | **Full Installation Guide**: [DOCUMENTATION.md - Installation](DOCUMENTATION.md#installation)
### Prerequisites
- **Windows OS** (required for COM automation)
- **Microsoft Outlook** installed and configured
- **Python 3.10+**
### Setup
1. Clone or download this repository
2. Install dependencies:
```bash
pip install -r requirements.txt
```
Or using the project file:
```bash
pip install -e .
```
3. Verify Outlook is running and configured with an account
4. Test the installation:
```bash
python tests/test_connection.py
```
## Usage
### Running the Server
Run the MCP server directly:
```bash
python src/outlook_mcp.py
```
Or using FastMCP's built-in CLI:
```bash
fastmcp run src/outlook_mcp.py
```
### Configuration for Cursor/Claude Desktop
Add this configuration to your MCP settings file:
**For Cursor** (`~/.cursor/mcp.json` or workspace settings):
```json
{
"mcpServers": {
"outlook": {
"command": "python",
"args": [
"C:/Users/YOUR_USERNAME/source/repos/MCP/src/outlook_mcp.py"
],
"env": {}
}
}
}
```
**For Claude Desktop** (`%APPDATA%/Claude/claude_desktop_config.json` on Windows):
```json
{
"mcpServers": {
"outlook": {
"command": "python",
"args": [
"C:/Users/YOUR_USERNAME/source/repos/MCP/src/outlook_mcp.py"
]
}
}
}
```
**Important**: Replace `YOUR_USERNAME` with your actual Windows username.
### Testing the Server
You can test the server using FastMCP's interactive mode:
```bash
fastmcp dev src/outlook_mcp.py
```
This will open an interactive prompt where you can test the tools.
## Tool Examples
> **More Examples**: [EXAMPLES.md](EXAMPLES.md) - Real-world use cases and workflows
### Reading Emails
```python
# Get last 10 unread emails
get_inbox_emails(limit=10, unread_only=True)
# Search for emails about "meeting"
search_emails(query="meeting", folder="inbox", limit=20)
```
### Sending Emails
```python
# Send a simple email
send_email(
to="colleague@company.com",
subject="Meeting Follow-up",
body="Hi, following up on our meeting...",
importance="high"
)
# Send email with HTML content and Outlook signature
send_email(
to="colleague@company.com",
subject="Project Update",
html_body="<h1>Update</h1><p>Here are the details...</p>",
signature_name="My Signature"
)
# Create a draft with multiple recipients and signature
create_draft_email(
to="team@company.com",
subject="Project Update",
body="Here's the latest update...",
cc="manager@company.com",
signature_name="My Signature"
)
```
### Calendar Management
```python
# Get next 7 days of events
get_calendar_events(days_ahead=7)
# Create a meeting
create_calendar_event(
subject="Team Standup",
start_time="2025-01-15 09:00",
end_time="2025-01-15 09:30",
location="Conference Room A",
required_attendees="team@company.com",
reminder_minutes=15
)
# Search for meetings
search_calendar_events(query="standup", days_range=30)
```
### Contact Management
```python
# Get all contacts
get_contacts(limit=50)
# Search for a contact
search_contacts(query="John Smith")
# Create a new contact
create_contact(
full_name="Jane Doe",
email="jane.doe@company.com",
company="Acme Corp",
job_title="Product Manager",
mobile_phone="+1-555-1234"
)
```
## Security & Permissions
- This server requires access to your Outlook data
- It uses Windows COM automation (no credentials stored)
- All operations are performed with your current Outlook profile's permissions
- Make sure Outlook is running and configured before starting the server
## Troubleshooting
### "Unable to connect to Outlook"
- Ensure Microsoft Outlook is installed and running
- Verify Outlook is configured with at least one email account
- Try restarting Outlook
### "ImportError: No module named 'win32com'"
- Install pywin32: `pip install pywin32`
- After installation, run: `python Scripts/pywin32_postinstall.py -install` (if needed)
### Permission Errors
- Run your terminal/IDE as Administrator (may be required for COM automation)
- Check that Outlook is not blocked by security policies
### Date Parsing Issues
- Use ISO format for dates: `2025-01-15 14:00`
- Supported formats: "YYYY-MM-DD HH:MM", "tomorrow 2pm", "next Monday 10am"
## Development
### Project Structure
```
mcp-outlook/
├── src/
│ ├── __init__.py
│ └── outlook_mcp.py # Main MCP server
├── pyproject.toml # Project configuration
├── requirements.txt # Dependencies
├── .gitignore
└── README.md
```
### Adding New Tools
To add a new tool, use the `@mcp.tool()` decorator:
```python
@mcp.tool()
def my_new_tool(param1: str, param2: int = 10) -> str:
"""
Tool description.
Args:
param1: Description of param1
param2: Description of param2 (default: 10)
Returns:
JSON string with results
"""
# Implementation
return json.dumps({"success": True, "data": "..."})
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black src/
ruff check src/
```
## Limitations
- **Windows Only**: Uses COM automation which is Windows-specific
- **Outlook Required**: Microsoft Outlook must be installed and running
- **Single Account**: Works with the default Outlook profile only
- **Performance**: Large mailboxes may have slower search performance
## Roadmap
### Recently Added
- [x] HTML email support
- [x] Outlook signature integration
- [x] Silent logging for cleaner integration
- [x] Outlook rules listing
- [x] Auto-learning email style from sent emails
- [x] Recursive folder search
### Planned Features
- [ ] Attachment download/upload support
- [ ] Meeting response handling (accept/decline/tentative)
- [ ] Out-of-office settings (get/set/disable)
- [ ] Task management integration
- [ ] Folder management (create, move, delete)
- [ ] Advanced filtering (flags, categories, custom properties)
- [ ] Email rules creation and modification
- [ ] Cross-platform support (investigate MAPI alternatives)
## License
MIT License - See LICENSE file for details.
## Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
- How to set up your development environment
- Code style guidelines (Black + Ruff)
- How to submit pull requests
- Roadmap and planned features
Quick Start for Contributors:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes and test thoroughly
4. Commit with conventional commits (`feat:`, `fix:`, `docs:`, etc.)
5. Push and create a Pull Request
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions.
## Documentation
- **[README.md](README.md)** (this file) - Overview and quick start
- **[DOCUMENTATION.md](DOCUMENTATION.md)** - Complete technical documentation
- **[EXAMPLES.md](EXAMPLES.md)** - Real-world examples and use cases
- **[QUICK_START.md](QUICK_START.md)** - 5-minute setup guide
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute
- **[CHANGELOG.md](CHANGELOG.md)** - Version history
## Support
For issues or questions:
- **Create an issue**: [GitHub Issues](https://github.com/YOUR_USERNAME/mcp-outlook/issues)
- **Check existing issues** for similar problems
- **Provide details**: Windows version, Outlook version, Python version, error logs
Before creating an issue:
1. Run `python tests/test_connection.py` and include the output
2. Check the [Troubleshooting](DOCUMENTATION.md#gestion-des-erreurs) section
3. Review [existing issues](https://github.com/YOUR_USERNAME/mcp-outlook/issues)
## Acknowledgments
- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Uses [pywin32](https://github.com/mhammond/pywin32) for COM automation
- Inspired by the MCP Atlassian server architecture
---
**Note**: This tool accesses your local Outlook data. Ensure you follow your organization's security policies when handling email and calendar data.
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo recent community issues