outlook-personal-mcp

Сервер MCP, который предоставляет Claude Code и Codex полный контроль над персональным почтовым ящиком Outlook.com и календарём через Microsoft Graph API. Написан на Python, поддерживает транспорт MCP stdio и использует OAuth device-code от имени пользователя, чтобы ваши учетные данные никогда не покидали ваш компьютер. Лицензия MIT.

Особенности

Почта — перечисление, поиск, чтение, отправка, ответы, пересылка, перемещение, копирование, пометка флагом, пометка как прочитано/непрочитано, удаление (мягкое или полное)
Черновики — создание, обновление, прикрепление локальных файлов, отправка
Папки — список, создание, переименование, удаление
Календарь — перечисление календарей, перечисление/поиск/получение/создание/обновление/удаление событий, ответы на приглашения (принять/отложить/возможный), проверка доступности
OAuth от имени пользователя — вы регистрируете собственное бесплатное приложение в Azure; сервер аутентифицируется с вашей учетной записью Microsoft и локально кэширует токен
Локальный stdio — запускается как дочерний процесс MCP-хоста; ваши данные почтового ящика никогда не проходят через третьи стороны

Необходимые условия

Python 3.10 или новее
uv (быстрый пакет Python и инструмент-раннер) — обязательно на этапе выполнения: сервер запускается через uvx, и он не входит в комплект вашего MCP-хоста (включая Claude Desktop). Установите его командой: curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) или powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows).
Личная учетная запись Microsoft (Outlook.com, Hotmail, Live и т. п.)
Бесплатная регистрация приложения в Azure (см. ниже — займёт около трёх минут)

Регистрация приложения Azure

Перейти в https://portal.azure.com → Microsoft Entra ID → App registrations → New registration.
Дайте ему любое имя (например, outlook-personal-mcp). В разделе Supported account types выберите Personal Microsoft accounts only. Redirect URI не требуется. Нажмите Register.
Откройте приложение → Authentication → Advanced settings → Allow public client flows → установить в Yes → Save. (Это требуется для flows входа с device-code, используемого этим сервером.)
Перейдите в API permissions → Add a permission → Microsoft Graph → Delegated permissions, затем добавьте:
- Mail.ReadWrite
- Mail.Send
- Calendars.ReadWrite
(По умолчанию включён User.Read; offline_access запрашивается автоматически на этапе выполнения — добавлять его не нужно.)
Скопируйте Application (client) ID с страницы обзорa. Это будет ваш OUTLOOK_MCP_CLIENT_ID.

Альтернатива: создание приложения с помощью Azure CLI

Если у вас установлен az CLI, регистрация выполняется одной командой:

az login --use-device-code --allow-no-subscriptions   # войдите своей личной учетной записью

az ad app create \
  --display-name "outlook-personal-mcp" \
  --sign-in-audience PersonalMicrosoftAccount \
  --is-fallback-public-client true \
  --required-resource-accesses '[{"resourceAppId":"00000003-0000-0000-c000-000000000000","resourceAccess":[{"id":"024d486e-b451-40bb-833d-3e66d98c5c73","type":"Scope"},{"id":"e383f46e-2787-4529-855e-0e479a3ffac0","type":"Scope"},{"id":"1ec239c2-d7c9-4623-a91a-a9775856bb36","type":"Scope"}]}]' \
  --query appId -o tsv

Печатный appId — это ваш OUTLOOK_MCP_CLIENT_ID. (GUID’ы соответствуют делегированным диапазонам Microsoft Graph: Mail.ReadWrite, Mail.Send и Calendars.ReadWrite.) Примечание: регистрируемое приложение может потребовать несколько минут для распространения — если вход не удался с кодом AADSTS700016 ("application … not found"), подождите несколько минут и повторите попытку.

Установка и первый вход

Сделайте одноразовый интерактивный вход. Программа выведет короткую URL и код; откройте URL в любом браузере, введите код, согласитесь с разрешениями — и готово. Токен будет сохранён в ~/.config/outlook-personal-mcp/token_cache.bin (права 600) и будет автоматически обновляться при последующих запусках — повторный вход не потребуется, пока токен обновления не истечёт или не будет аннулирован.

OUTLOOK_MCP_CLIENT_ID=<your-app-client-id> uvx mcp-outlook-personal login

Чтобы запустить последнюю нестабильную версию кода из исходников вместо выпуска PyPI, вместо mcp-outlook-personal используйте --from git+https://github.com/salahawad/outlook-personal-mcp mcp-outlook-personal.

Настройка Claude Code

Добавьте сервер в ваш файл проекта .mcp.json (или в ~/.claude/.mcp.json для всех проектов):

{
  "mcpServers": {
    "outlook": {
      "command": "uvx",
      "args": ["mcp-outlook-personal"],
      "env": { "OUTLOOK_MCP_CLIENT_ID": "<your-app-client-id>" }
    }
  }
}

Либо используйте CLI: claude mcp add.

Настройка Codex

Добавьте сервер в ~/.codex/config.toml:

[mcp_servers.outlook]
command = "uvx"
args = ["mcp-outlook-personal"]
env = { OUTLOOK_MCP_CLIENT_ID = "<your-app-client-id>" }

Установка как расширения Claude Desktop (.mcpb)

Этот сервер также упакован как расширение Claude Desktop (.mcpb). Соберите пакет из checkout:

npx @anthropic-ai/mcpb pack . dist/mcp-outlook-personal.mcpb

Затем в Claude Desktop откройте Settings → Extensions, установите файл dist/mcp-outlook-personal.mcpb, и при запросе укажите ваш Azure App Client ID (а при желании — дополнительные настройки).

Требование: расширение запускает сервер через uvx mcp-outlook-personal, поэтому uv должен быть установлен и находиться в вашем PATH — Claude Desktop не упаковывает его (см. Prerequisites). Codex и другие stdio-хосты используют приведённую выше конфигурацию вместо .mcpb.

Конфигурация (Environment Variables)

Переменная	Обязательная	По умолчанию	Описание
OUTLOOK_MCP_CLIENT_ID	Да	—	ID приложения Azure (Application (client) ID)
OUTLOOK_MCP_AUTHORITY	Нет	https://login.microsoftonline.com/consumers	URL authority MSAL (менять только если переходите на рабочую/учебную учетку)
OUTLOOK_MCP_TOKEN_CACHE	Нет	~/.config/outlook-personal-mcp/token_cache.bin	Путь к файлу кеша токена MSAL
OUTLOOK_MCP_FILE_ROOT	Нет	~/.local/share/outlook-personal-mcp/files	Только файлы в этой директории можно читать через add_attachment или записывать через download_attachment
OUTLOOK_MCP_MAX_FILE_BYTES	Нет	3145728	Максимальное количество байт, разрешённое для чтения локальных вложений и загрузки вложений
OUTLOOK_MCP_ALLOW_PERMANENT_DELETE	Нет	false	Установите в true, чтобы включить инструмент permanent_delete (необратимо)
OUTLOOK_MCP_DEBUG	Нет	false	Установите в true, чтобы логировать метод, URL и код статуса каждого запроса Graph в stderr. Никогда не логирует токены или содержимое сообщений.

Инструменты

Аккаунт

Инструмент	Описание
whoami	Возвращает профиль учетной записи Microsoft вошедшего в систему пользователя

Почта

Инструмент	Описание
list_messages	Список сообщений (новейшие вначале); при желании можно фильтровать по папке или показывать только непрочитанные
search_messages	Полнотекстовый поиск по всему почтовому ящику (Graph $search)
get_message	Получить одно сообщение; можно дополнительно включить полное тело
list_attachments	Список вложений сообщения (id, имя, размер, content type)
download_attachment	Скачать вложение в путь под OUTLOOK_MCP_FILE_ROOT (отказывается перезаписывать существующий файл)
send_mail	Отправить письмо
reply	Ответить на сообщение (reply_all — ответ всем)
forward	Переслать сообщение получателям с возможным комментарием
move_message	Переместить сообщение в другую папку
copy_message	Скопировать сообщение в другую папку
mark_read	Отметить сообщение как прочитанное или непрочитанное
flag_message	Пометить сообщение флагом или снять флаг
delete_message	Удалить сообщение (перемещается в Deleted Items; восстанавливаемость)
permanent_delete	Постоянно удалить сообщение (необратимо). Доступно только при `OUTLOOK_MCP_ALLOW_PERMANENT_DELETE=true`

Папки

Инструмент	Описание
list_folders	Перечень почтовых папок с учётом непрочитанных и общего числа сообщений
create_folder	Создать почтовую папку, при желании — вложенную в родительскую
rename_folder	Переименовать почтовую папку
delete_folder	Удалить почтовую папку (перемещается в Deleted Items)

Черновики

Инструмент	Описание
create_draft	Создать черновик письма (не отправлять)
update_draft	Обновить тему и/или тело черновика
add_attachment	Приложить локальный файл (обычный файл, не символьная ссылка, под OUTLOOK_MCP_FILE_ROOT) к черновику
send_draft	Отправить существующий черновик

Календарь

Инструмент	Описание
list_calendars	Перечень календарей пользователя
list_events	Перечень событий; если заданы начальная/конечная даты (ISO 8601) — возвращает окно времени
search_events	Поиск событий по тексту
get_event	Получить одно событие включая тело, участников и ссылку на онлайн-встречу
create_event	Создать событие календаря с опциональными участниками и онлайн-встречей
update_event	Обновить поля существующего события (изменяются только предоставленные поля)
delete_event	Удалить/аннулировать событие календаря
respond_event	Ответить на приглашение: принять, отклонить или tentative
find_availability	Получить свободное/занятое время для списка людей в заданном окне времени

Permanent Delete

Инструмент permanent_delete обходит папку Deleted Items и безвозвратно удаляет сообщение. По умолчанию он отключён — если OUTLOOK_MCP_ALLOW_PERMANENT_DELETE не установлен (или равен false), инструмент не регистрируется в MCP-сервере и не будет отображаться в списке инструментов.

Чтобы включить его, установите OUTLOOK_MCP_ALLOW_PERMANENT_DELETE=true в блоке окружения сервера в вашем .mcp.json / config.toml. Делайте это только если понимаете последствия: отката нет, и для личных аккаунтов отсутствует путь Recoverable Items.

Безопасность

Token cache — это учётные данные. Файл ~/.config/outlook-personal-mcp/token_cache.bin содержит долго действительный refresh token. Файл имеет режим 600, но обращайтесь с ним как с паролем — не коммитите его, не передавайте, храните на зашифрованном носителе.
Данные остаются локально. Сервер работает как дочерний процесс Claude Code / Codex через stdio. Содержимое вашего почтового ящика передаётся напрямую между MCP-хостом и Microsoft Graph API; третьи стороны не участвуют.
Отмена доступа. Чтобы отозвать доступ, удалите файл кеша токена и/или перейдите на https://account.microsoft.com/permissions и удалите согласие Azure-приложения. Вы также можете полностью удалить регистрацию Azure через портал.
Пути к файлам. download_attachment записывает только в OUTLOOK_MCP_FILE_ROOT и не перезаписывает существующие файлы. add_attachment читает только обычные файлы (не символьные ссылки) из OUTLOOK_MCP_FILE_ROOT. Относительные пути разрешаются внутри этого корня; абсолютные пути вне его (и любые пути, обходящие символьные ссылки) отклоняются. Обе команды также ограничивают размер файлов OUTLOOK_MCP_MAX_FILE_BYTES. Ознакомьтесь с этими путями перед подтверждением любой команды, работающей с файловой системой.

Разработка

git clone https://github.com/salahawad/outlook-personal-mcp
cd outlook-personal-mcp
uv venv && uv pip install -e ".[dev]"
uv run pytest
uv run ruff check .

Политика конфиденциальности

Этот сервер работает полностью на вашем компьютере и передаёт данные только между вашим устройством и Microsoft Graph API — без сторонних ретрансляторов, телеметрии и без получения каких-либо данных от держателя проекта. OAuth-токены кешируются локально по пути ~/.config/outlook-personal-mcp/token_cache.bin (с правами 600). См. PRIVACY.md для полной политики.

Лицензия

MIT — см. LICENSE.