# Outlook MCP Server

A Model Context Protocol (MCP) server that provides access to Microsoft Outlook email functionality, allowing LLMs and other MCP clients to read, search, and manage emails through a standardized interface.

## Features

- **Folder Management**: List available mail folders in your Outlook client
- **Email Listing**: Retrieve emails from specified time periods or date ranges
- **Date Range Filtering**: Filter emails by specific date ranges (supports YYYY-MM and YYYY-MM-DD formats)
- **Email Search**: Search emails by contact name, keywords, or phrases with OR operators
- **Email Details**: View complete email content, including attachments
- **Email Composition**: Create and send new emails
- **Email Replies**: Reply to existing emails

## Prerequisites

- Windows operating system
- Python 3.10 or later
- Microsoft Outlook installed and configured with an active account
- Claude Desktop or another MCP-compatible client

## Installation

1. Clone or download this repository
2. Install required dependencies:

```bash
pip install mcp>=1.2.0 pywin32>=305
```

3. Configure Claude Desktop (or your preferred MCP client) to use this server

## Configuration

### Claude Desktop Configuration

Add the following to your `MCP_client_config.json` file:

```json
{
  "mcpServers": {
    "outlook": {
      "command": "python",
      "args": ["Your path\\outlook_mcp_server_v2.py"],
      "env": {}
    }
  }
}
```

### Cursor Configuration

For Cursor IDE, add the following to your `mcp.json` file (usually located at `~/.cursor/mcp.json`):

**Important**: First, start the server manually or use a process manager:

```bash
python outlook_mcp_server_v2.py
```

Then add this configuration to your `mcp.json`:

```json
{
  "mcpServers": {
    "outlook_mcp_server": {
      "url": "http://127.0.0.1:8050/mcp",
      "connection_id": "outlook_mcp_server"
    }
  }
}
```

**Note**: Make sure the server is running before Cursor tries to connect. The server must be started with HTTP transport enabled (default).

## Usage

### Starting the Server

You can start the server directly:

```bash
python outlook_mcp_server_v2.py
```

Or allow an MCP client like Claude Desktop to start it via the configuration.

### Environment Variables (Optional)

The server supports the following environment variables for HTTP transport configuration:

- `MCP_TRANSPORT`: Transport type (default: "streamablehttp")
- `MCP_HTTP_HOST`: HTTP host (default: "127.0.0.1")
- `MCP_HTTP_PORT`: HTTP port (default: 8050)
- `MCP_HTTP_PATH`: HTTP path (default: "/mcp")

### Available Tools

The server provides the following tools:

1. `list_folders`: Lists all available mail folders in Outlook
2. `list_recent_emails`: Lists email titles from the specified number of days or date range
   - Supports date filtering with `start_date` and `end_date` parameters
   - Date formats: `YYYY-MM` (entire month) or `YYYY-MM-DD` (specific day)
3. `search_emails`: Searches emails by contact name or keyword within a time period or date range
   - Supports date filtering with `start_date` and `end_date` parameters
   - Date formats: `YYYY-MM` (entire month) or `YYYY-MM-DD` (specific day)
4. `get_email_by_number`: Retrieves detailed content of a specific email
5. `reply_to_email_by_number`: Replies to a specific email
6. `compose_email`: Creates and sends a new email

### Example Workflow

1. Use `list_folders` to see all available mail folders
2. Use `list_recent_emails` to view recent emails (e.g., from last 7 days, or from a specific date range)
3. Use `search_emails` to find specific emails by keywords within a date range
4. Use `get_email_by_number` to view a complete email
5. Use `reply_to_email_by_number` to respond to an email

## Examples

### Listing Recent Emails
```
Could you show me my unread emails from the last 3 days?
```

### Listing Emails by Date Range
```
Show me all emails from January 2024 (2024-01)
```

```
List emails from 2024-01-15 to 2024-02-20
```

```
Show me emails since 2024-03-01
```

### Searching for Emails
```
Search for emails about "project update OR meeting notes" in the last week
```

### Searching Emails by Date Range
```
Search for emails containing "budget" from 2024-01 to 2024-02
```

```
Find emails about "meeting" from 2024-01-15 to 2024-01-31
```

### Reading Email Details
```
Show me the details of email #2 from the list
```

### Replying to an Email
```
Reply to email #3 with: "Thanks for the information. I'll review this and get back to you tomorrow."
```

### Composing a New Email
```
Send an email to john.doe@example.com with subject "Meeting Agenda" and body "Here's the agenda for our upcoming meeting..."
```

## Troubleshooting

- **Connection Issues**: Ensure Outlook is running and properly configured
- **Permission Errors**: Make sure the script has permission to access Outlook
- **Search Problems**: For complex searches, try using OR operators between terms
- **Email Access Errors**: Check if the email ID is valid and accessible
- **Server Crashes**: Check Outlook's connection and stability

## Security Considerations

This server has access to your Outlook email account and can read, send, and manage emails. Use it only with trusted MCP clients and in secure environments.

## Limitations

- Currently supports text emails only (not HTML)
- Maximum email history is limited to 365 days when using `days` parameter
- Date range filtering supports formats: `YYYY-MM` (entire month) and `YYYY-MM-DD` (specific day)
- Search capabilities depend on Outlook's built-in search functionality
- Only supports basic email functions (no calendar, contacts, etc.)

---

# Outlook MCP Server (Русский язык)

Сервер Model Context Protocol (MCP), предоставляющий доступ к функциональности электронной почты Microsoft Outlook, позволяющий LLM и другим MCP-клиентам читать, искать и управлять письмами через стандартизированный интерфейс.

## Возможности

- **Управление папками**: Просмотр всех доступных почтовых папок в Outlook
- **Список писем**: Получение писем за указанный период времени или диапазон дат
- **Фильтрация по диапазону дат**: Фильтрация писем по конкретным диапазонам дат (поддерживаются форматы YYYY-MM и YYYY-MM-DD)
- **Поиск писем**: Поиск писем по имени контакта, ключевым словам или фразам с операторами OR
- **Детали письма**: Просмотр полного содержимого письма, включая вложения
- **Создание писем**: Создание и отправка новых писем
- **Ответы на письма**: Ответ на существующие письма

## Требования

- Операционная система Windows
- Python 3.10 или новее
- Установленный и настроенный Microsoft Outlook с активной учетной записью
- Claude Desktop или другой MCP-совместимый клиент

## Установка

1. Клонируйте или скачайте этот репозиторий
2. Установите необходимые зависимости:

```bash
pip install mcp>=1.2.0 pywin32>=305
```

3. Настройте Claude Desktop (или ваш предпочитаемый MCP-клиент) для использования этого сервера

## Конфигурация

### Конфигурация Claude Desktop

Добавьте следующее в ваш файл `MCP_client_config.json`:

```json
{
  "mcpServers": {
    "outlook": {
      "command": "python",
      "args": ["Ваш путь\\outlook_mcp_server_v2.py"],
      "env": {}
    }
  }
}
```

### Конфигурация Cursor

Для Cursor IDE добавьте следующее в ваш файл `mcp.json` (обычно находится в `~/.cursor/mcp.json`):

**Важно**: Сначала запустите сервер вручную или используйте менеджер процессов:

```bash
python outlook_mcp_server_v2.py
```

Затем добавьте эту конфигурацию в ваш `mcp.json`:

```json
{
  "mcpServers": {
    "outlook_mcp_server": {
      "url": "http://127.0.0.1:8050/mcp",
      "connection_id": "outlook_mcp_server"
    }
  }
}
```

**Примечание**: Убедитесь, что сервер запущен перед тем, как Cursor попытается подключиться. Сервер должен быть запущен с включенным HTTP транспортом (по умолчанию).

## Использование

### Запуск сервера

Вы можете запустить сервер напрямую:

```bash
python outlook_mcp_server_v2.py
```

Или позволить MCP-клиенту, такому как Claude Desktop, запустить его через конфигурацию.

### Переменные окружения (опционально)

Сервер поддерживает следующие переменные окружения для настройки HTTP транспорта:

- `MCP_TRANSPORT`: Тип транспорта (по умолчанию: "streamablehttp")
- `MCP_HTTP_HOST`: HTTP хост (по умолчанию: "127.0.0.1")
- `MCP_HTTP_PORT`: HTTP порт (по умолчанию: 8050)
- `MCP_HTTP_PATH`: HTTP путь (по умолчанию: "/mcp")

### Доступные инструменты

Сервер предоставляет следующие инструменты:

1. `list_folders`: Список всех доступных почтовых папок в Outlook
2. `list_recent_emails`: Список заголовков писем за указанное количество дней или диапазон дат
   - Поддерживает фильтрацию по датам с параметрами `start_date` и `end_date`
   - Форматы дат: `YYYY-MM` (весь месяц) или `YYYY-MM-DD` (конкретный день)
3. `search_emails`: Поиск писем по имени контакта или ключевому слову в пределах периода времени или диапазона дат
   - Поддерживает фильтрацию по датам с параметрами `start_date` и `end_date`
   - Форматы дат: `YYYY-MM` (весь месяц) или `YYYY-MM-DD` (конкретный день)
4. `get_email_by_number`: Получение подробного содержимого конкретного письма
5. `reply_to_email_by_number`: Ответ на конкретное письмо
6. `compose_email`: Создание и отправка нового письма

### Примерный рабочий процесс

1. Используйте `list_folders` для просмотра всех доступных почтовых папок
2. Используйте `list_recent_emails` для просмотра недавних писем (например, за последние 7 дней или за конкретный диапазон дат)
3. Используйте `search_emails` для поиска конкретных писем по ключевым словам в пределах диапазона дат
4. Используйте `get_email_by_number` для просмотра полного письма
5. Используйте `reply_to_email_by_number` для ответа на письмо

## Примеры

### Просмотр недавних писем
```
Покажи мне непрочитанные письма за последние 3 дня
```

### Просмотр писем по диапазону дат
```
Покажи мне все письма за январь 2024 года (2024-01)
```

```
Покажи письма с 2024-01-15 по 2024-02-20
```

```
Покажи письма с 2024-03-01
```

### Поиск писем
```
Найди письма о "обновление проекта OR заметки встречи" за последнюю неделю
```

### Поиск писем по диапазону дат
```
Найди письма содержащие "бюджет" с 2024-01 по 2024-02
```

```
Найди письма о "встрече" с 2024-01-15 по 2024-01-31
```

### Просмотр деталей письма
```
Покажи мне детали письма №2 из списка
```

### Ответ на письмо
```
Ответь на письмо №3: "Спасибо за информацию. Я изучу это и отвечу завтра."
```

### Создание нового письма
```
Отправь письмо на john.doe@example.com с темой "Повестка встречи" и текстом "Вот повестка дня для нашей предстоящей встречи..."
```

## Решение проблем

- **Проблемы с подключением**: Убедитесь, что Outlook запущен и правильно настроен
- **Ошибки прав доступа**: Убедитесь, что скрипт имеет разрешение на доступ к Outlook
- **Проблемы с поиском**: Для сложных запросов попробуйте использовать операторы OR между терминами
- **Ошибки доступа к письмам**: Проверьте, что ID письма действителен и доступен
- **Сбои сервера**: Проверьте подключение и стабильность Outlook

## Вопросы безопасности

Этот сервер имеет доступ к вашей учетной записи Outlook и может читать, отправлять и управлять письмами. Используйте его только с доверенными MCP-клиентами и в безопасных средах.

## Ограничения

- В настоящее время поддерживаются только текстовые письма (не HTML)
- Максимальная история писем ограничена 365 днями при использовании параметра `days`
- Фильтрация по диапазону дат поддерживает форматы: `YYYY-MM` (весь месяц) и `YYYY-MM-DD` (конкретный день)
- Возможности поиска зависят от встроенной функциональности поиска Outlook
- Поддерживаются только базовые функции электронной почты (без календаря, контактов и т.д.)