MCP Outlook

A Model Context Protocol (MCP) server for Microsoft Outlook integration.

Version: 1.0.3 | Documentation: DOCUMENTATION.md | Contributing: CONTRIBUTING.md | Examples: EXAMPLES.md

Overview

This MCP server provides AI assistants with the ability to interact with Microsoft Outlook, including:

• Email Management: Read, search, send, and draft emails with HTML support and Outlook signatures

• Attachment Management: List, download, and send email attachments with robust detection

• Calendar Management: View, create, and search calendar events

• Contact Management: View, create, and search contacts

• Folder Management: List folders, search in custom folders, and view Outlook rules

• Auto-Learning Style: Automatically learns your email formatting preferences (font, size, color) from sent emails

Features

Detailed documentation for each feature: DOCUMENTATION.md

5 Email Tools (Documentation)

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

3 Attachment Tools (Documentation)

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

3 Calendar Tools (Documentation)

• 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

3 Contact Tools (Documentation)

• get_contacts - Retrieve contacts with optional name filtering

• create_contact - Create new contacts

• search_contacts - Search contacts by name, email, or company

3 Folder Tools (Documentation)

• 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 for detailed performance information.

Installation

Quick Start Guide: QUICK_START.md | Full Installation Guide: 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:

pip install -r requirements.txt

Or using the project file:

pip install -e .

3. Verify Outlook is running and configured with an account

4. Test the installation:

python tests/test_connection.py

Usage

Running the Server

Run the MCP server directly:

python src/outlook_mcp.py

Or using FastMCP's built-in CLI:

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

{
  "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):

{
  "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:

fastmcp dev src/outlook_mcp.py

This will open an interactive prompt where you can test the tools.

Tool Examples

More Examples: EXAMPLES.md - Real-world use cases and workflows

Reading Emails

# 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

# 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

# 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

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

@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

pytest

Code Formatting

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

• HTML email support

• Outlook signature integration

• Silent logging for cleaner integration

• Outlook rules listing

• Auto-learning email style from sent emails

• 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 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 for detailed instructions.

Documentation

• README.md (this file) - Overview and quick start

• DOCUMENTATION.md - Complete technical documentation

• EXAMPLES.md - Real-world examples and use cases

• QUICK_START.md - 5-minute setup guide

• CONTRIBUTING.md - How to contribute

• CHANGELOG.md - Version history

Support

For issues or questions:

• Create an issue: GitHub 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 section

3. Review existing issues

Acknowledgments

• Built with FastMCP

• Uses 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.