README - Mcp Outlook by ssssofias

Outlook MCP Server

A lightweight MCP Server for seamless integration with Microsoft Outlook, enabling MCP clients to interact with emails for specific users. Developed by sofias tech.

Features

This server provides a clean interface to Outlook email resources through the Model Context Protocol (MCP), with operations for reading, searching, creating, updating, and deleting emails.

Tools

The server implements the following tools:

Get_Outlook_Email: Retrieves a specific email by its unique ID.
Search_Outlook_Emails: Searches emails using OData filter syntax (e.g., "subject eq 'Update'", "isRead eq false") across multiple folders.
Download_Outlook_Emails_By_Date: Downloads emails within a specific date range using ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Create_Outlook_Draft_Email: Creates a new draft email with the specified subject, body, and recipients.
Update_Outlook_Draft_Email: Updates an existing draft email specified by its ID.
Delete_Outlook_Email: Deletes an email by its ID (moves it to the Deleted Items folder).

All tools require a user_email parameter to specify which mailbox to access.

Architecture

The server is built with efficiency and clarity in mind:

Utilizes the Microsoft Graph API via the office365-rest-python-client library
Modular design with clear separation between:
- resources.py: Core API functionality for interacting with Outlook
- tools.py: MCP tool definitions that wrap resource functions
- common.py: Shared components and configuration
- server.py: Main entry point that initializes and runs the MCP server
Uses environment variables for secure configuration
Supports accessing multiple user mailboxes through application permissions

Recent Optimizations

The codebase has been recently optimized with the following improvements:

Enhanced Exception Handling
- Implementation of decorators (exception_handler and safe_operation) for consistent error handling
- More robust error recovery, ensuring the service remains functional even when processing problematic emails
Performance Improvements
- Consolidated text processing pipeline in clean_utils.py reducing processing overhead
- Optimized attribute access patterns in format_utils.py for faster message parsing
- Streamlined regular expressions for better text processing efficiency
Code Maintainability
- Reduced codebase size by approximately 50% while maintaining full functionality
- Improved function organization with better separation of concerns
- Enhanced code readability with clearer structure and purpose

These optimizations improve the reliability and performance of the service without changing its core functionality or external interfaces. All tools continue to operate with the same parameters and return values, but with better internal processing.

Setup

Register an app in Azure AD
Grant the necessary Microsoft Graph API permissions at the application level (not delegated):
- Mail.ReadWrite
- Mail.Send
- User.Read
Obtain the client ID, tenant ID, and create a client secret
Have an admin grant consent for these permissions at the organization level

Environment Variables

Create a .env file with the following variables:

ID_CLIENT: Your Azure AD application client ID.
APP_SECRET: Your Azure AD application client secret.
TENANT_ID: Your Microsoft Directory (tenant) ID.

Note: The user email is now passed as a parameter to each tool rather than being defined as an environment variable.

Quickstart

Installation

Install the package in editable mode for development:

pip install -e .

Or install from PyPI once published:

pip install mcp-outlook

Using uv:

uv pip install mcp-outlook

Claude Desktop Integration

To integrate with Claude Desktop, update the configuration file:

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

Standard Integration

"mcpServers": {
  "outlook": {
    "command": "mcp-outlook",
    "env": {
      "ID_CLIENT": "your-app-id",
      "APP_SECRET": "your-app-secret",
      "TENANT_ID": "your-tenant-id"
    }
  }
}

Using uvx

"mcpServers": {
  "outlook": {
    "command": "uvx",
    "args": [
      "mcp-outlook"
    ],
    "env": {
      "ID_CLIENT": "your-app-id",
      "APP_SECRET": "your-app-secret",
      "TENANT_ID": "your-tenant-id"
    }
  }
}

Development

Requirements

Python 3.10+
Dependencies listed in pyproject.toml

Local Development

Clone the repository.

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install development dependencies:
```
pip install -e .
```

Create a .env file in the project root with your Azure AD app credentials:

ID_CLIENT=your-app-id
APP_SECRET=your-app-secret
TENANT_ID=your-tenant-id

Run the server:
```
python -m mcp_outlook_server
```
Note: Ensure the module name matches your main execution script if different.

Debugging

For debugging the MCP server, you can use the MCP Inspector:

npx @modelcontextprotocol/inspector -- python -m mcp_outlook_server

Example Usage

When using the tools through Claude or another MCP client, you'll need to specify the user email for each operation:

"Get emails from last week for "
"Search for emails with 'Project Update' in the subject for "
"Create a draft email for to send to the team"
"Delete the email with ID ABC123 from 's inbox"

License

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