MCP Outlook Tools

A Model Context Protocol (MCP) server implementation that enables AI assistants to interact with Microsoft Outlook for calendar management, email operations, and search functionality.

Features

📅 Calendar Management
- Get calendar items within a date range
- Add new appointments with full details
- Support for categories and busy status
📧 Email Operations
- Send emails with To/CC recipients
- Display confirmation before sending
- Full body formatting support
🔍 Email Search
- Search emails by date and keyword
- Extract user information from addresses
- Japanese text encoding support

Requirements

Windows OS (required for pywin32)
Microsoft Outlook installed and configured
Python 3.10 or higher
MCP-compatible AI assistant (e.g., Claude Desktop)

Installation

Clone the repository:

git clone https://github.com/wmoto-ai/mcp-outlook-tools.git
cd mcp-outlook-tools

Install dependencies using uv:

uv pip install -e .

Or using pip:

pip install -e .

Configuration

For Claude Desktop

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.jsonmacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "outlook-tools": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/path/to/mcp-outlook-tools",
        "run",
        "--with-editable",
        ".",
        "-m",
        "outlook_tools.server"
      ],
      "cwd": "C:/path/to/mcp-outlook-tools",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Usage

Once configured, the following tools are available in your AI assistant:

`add_appointment`

Add a new appointment to Outlook calendar
Parameters:
- subject: Appointment title
- start_time: Start datetime (YYYY-MM-DD HH:MM)
- end_time: End datetime (YYYY-MM-DD HH:MM)
- location: Meeting location (optional)
- description: Detailed description (optional)
- categories: Comma-separated categories (optional)
- busy_status: 0=Free, 1=Tentative, 2=Busy, 3=Out of Office (default: 1)

`get_calendar`

Get calendar items for a date range
Parameters:
- start_date: Start date (YYYY-MM-DD)
- end_date: End date (YYYY-MM-DD)

`send_email`

Send an email via Outlook
Parameters:
- to: Recipient email addresses (semicolon-separated)
- cc: CC recipients (semicolon-separated)
- subject: Email subject
- body: Email body text

Project Structure

mcp-outlook-tools/
├── src/
│   └── outlook_tools/
│       ├── __init__.py
│       ├── server.py           # MCP server implementation
│       ├── calendar_service.py # Calendar operations
│       └── search_service.py   # Email search operations
├── test/                       # Test files
├── pyproject.toml             # Project configuration
└── README.md                  # This file

Development

Running Tests

pytest test/

Type Checking

pyright src/

Linting

ruff check src/

Security Notes

This tool requires access to your local Outlook installation
Emails are displayed before sending for user confirmation
No credentials are stored in the code
All operations use Windows COM interface with existing Outlook authentication

Limitations

Windows only (due to pywin32 dependency)
Requires Outlook to be installed and configured
Time zone handling assumes JST (+9 hours)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with FastMCP framework
Uses pywin32 for Outlook COM interface

MCP Outlook Tools