MCP Outlook Tools

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

🚀 Quick Start

The MCP Outlook Tools is a powerful tool that allows AI assistants to interact with Microsoft Outlook, enabling functions such as calendar management, email operations, and search.

✨ Features

• 📅 Calendar Management

  • Retrieve calendar items within a specified date range.
  • Add new appointments with comprehensive details.
  • Support for categorizing appointments and setting busy status.

• 📧 Email Operations

  • Send emails to specified To/CC recipients.
  • Display a confirmation prompt before sending emails.
  • Offer full support for email body formatting.

• 🔍 Email Search

  • Search for emails by date and keyword.
  • Extract user information from email addresses.
  • Provide support for Japanese text encoding.

📦 Installation

1. Clone the repository:

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

2. Install dependencies. You can choose one of the following methods:
   • Using uv:

uv pip install -e .

- Using pip:

pip install -e .

📚 Documentation

Configuration

For Claude Desktop

Add the following content to your Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/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:

💻 Usage Examples

Basic Usage

### `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 the Windows COM interface with existing Outlook authentication.

Limitations

• Only available on Windows due to the 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 the FastMCP framework.
• Uses pywin32 for the Outlook COM interface.