M365 Attachment Reader MCP

Удаленный MCP-сервер для Claude, который читает электронные письма Outlook и глубоко анализирует вложения через Microsoft Graph API.

Поддержка обработки вложений теперь включает PDF, отсканированные PDF с OCR, Word, PowerPoint, Excel, CSV, обычный текст, изображения, архивы и файлы Outlook .msg.

Статус: Ранняя версия для тестирования на Windows. Функциональна для личного использования и частных рабочих процессов, но еще не является готовым к эксплуатации многопользовательским сервисом.

Зачем это нужно

Встроенный коннектор Microsoft 365 для Claude может перечислять письма, читать тело сообщений и проверять календари. Но он не может читать содержимое самих вложений.

Это означает, что когда вы спрашиваете: «О чем PDF в моем последнем письме?», Claude видит метаданные вложения, но не текст, таблицы, изображения или вложенные документы внутри него.

Этот проект заполняет данный пробел.

Что он делает

Этот сервер находится между Claude и Microsoft 365 в качестве удаленной HTTP MCP-конечной точки. Он:

Аутентифицируется в Microsoft 365 через поток кода устройства (device code flow)
Перечисляет письма Outlook и их вложения через Microsoft Graph
Загружает вложения на бэкенде
Анализирует содержимое файлов и возвращает структурированный текст и блоки изображений напрямую в Claude

Поддерживаемые форматы

Формат	Что извлекается
PDF	Полное текстовое содержимое
Отсканированный PDF	Текст OCR, плюс опционально отрисованные изображения страниц
DOCX	Текст и встроенные изображения
DOC	Текстовое содержимое
PPTX / PPTM / PPSX / POTX	Текст слайдов, заметки и встроенные изображения
PPT	Попытка извлечения текста из устаревших форматов
XLSX / XLS / CSV	Все листы конвертируются в CSV
JPG / JPEG / PNG / GIF / WEBP / BMP / TIFF	Возвращаются как блоки изображений MCP для визуального анализа
ZIP / RAR / 7Z	Содержимое архива рекурсивно анализируется файл за файлом
MSG	Тема, отправитель, тело и встроенные вложения
TXT / MD / JSON / XML / HTML	Необработанный текст
Outlook `itemAttachment`	Текстовое содержимое

Обработка изображений — ключевое отличие: сервер может возвращать отдельные вложения-изображения как блоки изображений MCP, извлекать встроенные изображения из файлов DOCX и PPTX, а также использовать OCR для отсканированных PDF, если в них отсутствует текстовый слой.

Инструменты MCP

Инструмент	Описание
`health_check`	Проверка работоспособности сервера
`begin_auth`	Запуск процесса входа через код устройства
`auth_status`	Проверка статуса аутентификации
`list_recent_messages`	Список недавних писем Outlook
`list_email_attachments`	Список вложений для конкретного письма
`read_email_attachment`	Загрузка, анализ и возврат содержимого вложения

Эти короткие названия инструментов являются псевдонимами для базовых инструментов m365_*, зарегистрированных сервером.

Примеры использования

Розничная торговля / Операции по продажам

«Получи последние 5 писем с ежедневными отчетами, прочитай вложения Excel и проанализируй динамику продаж по всем магазинам за прошлую неделю.»

Финансы / Бухгалтерия

«Найди последнее письмо от нашего поставщика с темой "Счет", прочитай вложение PDF и извлеки общую сумму, срок оплаты и позиции счета.»

Юридические вопросы / Проверка контрактов

«Открой самое последнее письмо от legal@partner.com, прочитай вложение Word или PowerPoint и сделай краткое изложение ключевых условий.»

Руководящая отчетность

«Прочитай вложение с еженедельным отчетом совета директоров из последнего письма финансового директора и сделай краткое изложение графиков и ключевых показателей.»

HR / Рекрутинг

«Найди письма от recruiting@company.com с вложениями, прочитай каждый PDF-файл с резюме и создай сравнительную таблицу кандидатов.»

Цепочки поставок / Закупки

«Прочитай последний архив с коммерческими предложениями поставщиков, извлеки из него электронные таблицы и сравни цены за единицу товара с предыдущим предложением.»

Архитектура

Claude Chat -> Cloudflare Tunnel -> Local Express Server -> Microsoft Graph API
                (public URL)       (localhost:8080)      (Outlook data)
                                           |
                                    Parse attachments
                              (pdf-parse, tesseract.js,
                               mammoth, xlsx, adm-zip,
                                msgreader, archive tools)

Для локального тестирования Cloudflare Quick Tunnel открывает локальный сервер для интернета. Claude подключается через пользовательский коннектор (Custom Connector), указывающий на URL туннеля.

Предварительные требования

Windows 10/11 с PowerShell
Node.js
Учетная запись Microsoft 365 / Outlook
Учетная запись Claude с поддержкой пользовательских коннекторов

Настройка

1. Создание регистрации приложения в Microsoft Entra

Перейдите в Центр администрирования Microsoft Entra -> Регистрация приложений -> Новая регистрация.

Имя: m365-mcp-remote
Поддерживаемые типы учетных записей: Учетные записи в любом каталоге организации и личные учетные записи Microsoft

Затем:

Скопируйте идентификатор приложения (клиента) и идентификатор каталога (арендатора) со страницы «Обзор»
Перейдите в «Аутентификация» -> Включите «Разрешить потоки общедоступного клиента» -> Сохранить
Перейдите в «Разрешения API» -> Добавить разрешение -> Microsoft Graph -> Делегированные разрешения -> Добавьте User.Read и Mail.Read -> Предоставить согласие администратора

2. Клонирование и установка

git clone https://github.com/Zacccck/MCP.git
cd MCP
npm install

3. Настройка окружения

cp .env.example .env

Отредактируйте .env и вставьте идентификатор клиента вашего приложения:

M365_CLIENT_ID=your-application-client-id-here
M365_TENANT_ID=common

4. Запуск сервера

npm start

Вы должны увидеть:

Custom M365 HTTP MCP server listening at http://127.0.0.1:8080/mcp

5. Открытие через Cloudflare Tunnel

В новом окне PowerShell:

winget install --id Cloudflare.cloudflared

Затем запустите:

cloudflared tunnel --url http://127.0.0.1:8080

Скопируйте сгенерированный URL https://xxxxx.trycloudflare.com.

6. Добавление в Claude как пользовательский коннектор

В чате Claude:

Нажмите кнопку + рядом с полем ввода
Откройте Connectors -> Add connector -> Custom Connector
Введите URL: https://xxxxx.trycloudflare.com/mcp

Используйте https:// и добавьте /mcp в конце. Не используйте http://127.0.0.1:8080/mcp.

7. Аутентификация

В Claude напишите:

Please call begin_auth

Claude вернет URL для входа и код устройства. Откройте URL, введите код и завершите вход в Microsoft. Затем проверьте с помощью:

Please call auth_status

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

Show me my recent outlook emails with attachments

Summarize the contents of the attachments from the email

Важные ограничения

Один пользователь: состояние аутентификации хранится в памяти. Один экземпляр сервера соответствует одной учетной записи Microsoft.
Требуются два процесса: и node server.mjs, и cloudflared tunnel должны оставаться запущенными во время использования.
Quick Tunnel предназначен только для тестирования: URL Cloudflare меняется каждый раз при перезапуске cloudflared.
Требуется ручная настройка: регистрация приложения Azure, конфигурация .env и настройка коннектора по-прежнему выполняются вручную.

Устранение неполадок

Проблема	Решение
Claude не может найти инструменты MCP	Проверьте, запущены ли сервер Node и туннель Cloudflare. URL туннеля мог измениться после перезапуска.
Ошибка `invalid_grant`	Перепроверьте регистрацию приложения: поддерживаемые типы учетных записей, включенные потоки общедоступного клиента и предоставленные разрешения `User.Read` и `Mail.Read`.
Код устройства не отображается	Убедитесь, что `begin_auth` был вызван успешно. Не придумывайте код вручную.
Хотите сменить учетную запись	Остановите сервер Node, перезапустите его с помощью `npm start` и используйте окно браузера в режиме инкогнито для входа.

Структура проекта

MCP/
|-- server.mjs
|-- package.json
|-- .env.example
|-- .gitignore
|-- LICENSE
`-- README.md

Дорожная карта

[ ] Упрощенная первоначальная настройка
[ ] Выход из учетной записи и переключение без перезапуска
[ ] Режим фоновой службы Windows
[ ] Руководство по развертыванию в продакшн
[ ] Архитектура многопользовательских сессий
[ ] Более широкая поддержка языков OCR и улучшенное обобщение больших файлов

Примечания по безопасности

Это локальная реализация для тестирования и прототипирования. Она не готова к промышленному использованию для публичного развертывания. Перед публичным развертыванием потребуется аутентификация перед /mcp, изоляция сессий для каждого пользователя, безопасное хранение токенов, ограничение частоты запросов (rate limiting) и надлежащая инфраструктура.

Claude-Read-Outlook-Attachments