Outlook MCP Server

Model Context Protocol сервер, связывающий Claude с Microsoft Outlook + Teams (почта, календарь, контакты, задачи, файлы, записи и расшифровки встреч Teams), развернутый на Cloudflare Workers.

Форкните этот репозиторий, разверните на своем аккаунте Cloudflare, зарегистрируйте приложение Microsoft Azure AD, укажите Claude.ai на ваш worker — и Claude сможет читать и записывать ваши данные Microsoft 365 через естественный язык.

Построен на @bashco/mcp-toolkit — OAuth, пер-клиентские bearer-токены, ограничение скорости, структурированное логирование, типизированная диспетчеризация инструментов — все это обрабатывается общей библиотекой.

Что получает Claude — 39 инструментов в 7 областях

• Почта: список писем, чтение письма, поиск, ответ, пересылка, удаление, отправка, перемещение между папками, создание черновика, обновление черновика, отправка черновика, отложенная отправка

• Календарь: список событий, список повторений событий, создание, обновление, удаление, отмена события, ответ на событие

• Контакты: список, создание контакта, обновление контакта

• Задачи: список списков задач, список задач, создание задачи

• Файлы: список файлов, поделиться файлом

• Встречи Teams: список последних записей (отправная точка для обнаружения — находит встречи с контентом за последние N дней, без ввода данных), поиск онлайн-встречи, список записей встречи, список расшифровок встречи, получение содержимого расшифровки. Каждый инструмент для конкретной встречи принимает любой из meeting_id, calendar_event_id или join_url — так что запланированные встречи (разрешаемые через событие), ad-hoc / звонки Meet-now (разрешаемые через join URL, вставленный из чата Teams) и прямые поиски по ID — все работают.

• Разговор: получить разговор (полную ветку)

• Настройки: получить настройки почтового ящика, установить автоответ

Полный живой каталог доступен на MCP-эндпоинте tools/list после развертывания.

Related MCP server: MCP Outlook Server

Как работает аутентификация

Два уровня:

1. Claude.ai ↔ ваш worker — стандартный поток MCP OAuth 2.0 + PKCE. Каждый клиент Claude получает уникальный bearer-токен; ваш MCP_APPROVAL_CODE — это то, что вы вставляете на /authorize один раз, чтобы выпустить этот bearer.

2. Ваш worker ↔ Microsoft Graph — проксированный OAuth. Вы авторизуете Microsoft один раз, посетив /oauth/start на вашем развернутом worker; refresh-токены хранятся зашифрованными в Cloudflare KV. Обновление происходит автоматически.

Настройка — разверните свою копию

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

• Аккаунт Cloudflare (бесплатный план подходит)

• Wrangler CLI установлен и выполнен вход (wrangler login)

• Node.js 22+

• Аккаунт Microsoft (личный, рабочий или учебный) с доступом к регистрации приложений Azure AD на entra.microsoft.com

1. Форк и клонирование

git clone https://github.com/<your-username>/outlook-mcp
cd outlook-mcp
npm install

2. Создайте пространство имен KV

wrangler kv:namespace create OAUTH_KV

Wrangler выведет что-то вроде:

🌀 Creating namespace with title "outlook-mcp-OAUTH_KV"
✨ Success! Add the following to your configuration file:
[[kv_namespaces]]
binding = "OAUTH_KV"
id = "abc123def456..."

Отредактируйте wrangler.jsonc и замените существующий id в kv_namespaces на то, что только что вывел wrangler.

wrangler.jsonc намеренно включен в репозиторий — Wrangler и CI-деплой оба нуждаются в нем, и он не содержит секретов (только id вашего пространства имен KV, публичный client id Azure и URL worker). wrangler.jsonc.example содержит ту же структуру с плейсхолдерами, если вы предпочитаете начать с чистой копии. Настоящие секреты передаются через wrangler secret put и никогда не появляются в этом файле.

3. Зарегистрируйте приложение Microsoft Azure AD

1. Перейдите на entra.microsoft.com → Identity → Applications → App registrations → New registration

2. Name: любое (например, "Claude Outlook MCP")

3. Supported account types:

   • "Accounts in this organizational directory only", если вы хотите ограничить одним тенантом

   • "Accounts in any organizational directory and personal Microsoft accounts" для максимально широкой поддержки

4. Redirect URI: пока оставьте пустым — вернетесь после шага 6

5. Нажмите Register

6. На странице обзора приложения запишите:

   • Application (client) ID → это ваш MICROSOFT_CLIENT_ID

   • Directory (tenant) ID → это ваш MICROSOFT_TENANT_ID (или используйте строку common для мультитенантной поддержки + личных аккаунтов)

7. API permissions → добавьте следующие делегированные разрешения Microsoft Graph:

   • Mail.ReadWrite, Mail.Send

   • Calendars.ReadWrite

   • Contacts.ReadWrite

   • Tasks.ReadWrite

   • Files.Read.All (или Files.ReadWrite.All, если нужны инструменты для файлов с записью)

   • User.Read

   • offline_access (требуется для refresh-токенов)

   • MailboxSettings.ReadWrite

   • Sites.Read.All

   • OnlineMeetings.Read

   • OnlineMeetingRecording.Read.All — требуется согласие администратора

   • OnlineMeetingTranscript.Read.All — требуется согласие администратора

   После добавления двух разрешений .Read.All нажмите "Grant admin consent for [имя тенанта]" на странице API permissions. Без согласия администратора инструменты записи/расшифровки встреч будут возвращать 403.

8. Certificates & secrets → New client secret → запишите значение (в 1Password). Это ваш MICROSOFT_CLIENT_SECRET. Вы можете увидеть его только один раз — скопируйте немедленно.

4. Обновите wrangler.jsonc

Отредактируйте wrangler.jsonc и замените оба:

• vars.MICROSOFT_CLIENT_ID — на Application ID из шага 3.6

• vars.MICROSOFT_TENANT_ID — на Directory ID из шага 3.6 (или common)

5. Установите секреты

Сгенерируйте новый код одобрения:

openssl rand -base64 32

Сохраните его в менеджере паролей, затем отправьте в Cloudflare:

wrangler secret put MCP_APPROVAL_CODE          # paste the value from above
wrangler secret put MICROSOFT_CLIENT_SECRET    # from Step 3.8

6. Первое развертывание (чтобы узнать URL worker)

npm run deploy

Wrangler выведет URL вашего worker — что-то вроде https://outlook-mcp.<ваш-аккаунт>.workers.dev. Сохраните его.

7. Обновите WORKER_URL и redirect URI Microsoft

Нужны два обновления:

a) Отредактируйте wrangler.jsonc — в vars замените WORKER_URL на URL из шага 6.

b) В приложении Azure AD (entra.microsoft.com → ваше приложение → Authentication → Add a platform → Web) установите redirect URI на <url-вашего-worker>/oauth/callback. Без этого Microsoft отклонит поток OAuth.

Затем повторно разверните:

npm run deploy

8. Подключите Microsoft (один раз)

В браузере посетите <url-вашего-worker>/oauth/start. Вставьте ваш MCP_APPROVAL_CODE. Вы будете перенаправлены в Microsoft для входа и предоставления областей из шага 3.7. После согласия ваши зашифрованные вышестоящие токены попадут в OAUTH_KV. Обновление будет происходить автоматически.

Вы можете подтвердить подключение, посетив <url-вашего-worker>/oauth/status — должно быть connected: true.

9. Подключите Claude.ai

1. В Claude.ai перейдите в Settings → Integrations → Add MCP server

2. Server URL: <url-вашего-worker>/mcp

3. Claude.ai перенаправит вас на страницу /authorize вашего worker

4. Вставьте ваш MCP_APPROVAL_CODE и подтвердите

5. Вы подключены — теперь у Claude есть 38 инструментов Outlook + Teams

Подпись электронной почты

Необязательно. При настройке Worker добавляет вашу подпись при отправке, так что вызывающий агент никогда не должен ее воспроизводить — ее нельзя перефразировать, обрезать или забыть.

Передайте include_signature: true в любой из send_email, schedule_send, reply_to_email, forward_email, create_draft, update_draft, create_reply_draft, create_reply_all_draft или create_forward_draft. По умолчанию false, поэтому существующие вызывающие коды не затрагиваются.

Для черновиков подпись вставляется в момент создания черновика, а не при отправке — send_draft принимает только id и никогда не касается тела. Это означает, что подписанное тело — это то, что вы просматриваете перед отправкой. При update_draft флаг применяется только когда вы также передаете новый body (иначе нечего подписывать, и это заменило бы черновик телом только с подписью); этот случай сообщается в notes ответа, а не молча стирает черновик.

Приглашения в календаре

create_calendar_event и update_calendar_event принимают тот же флаг include_signature, добавляя подпись к описанию события. Он использует тот же блок SIGNATURE_HTML, что и электронная почта — включая его маркетинговые кнопки призыва к действию — поэтому он больше подходит для приглашения для клиента, чем для внутренней встречи; именно поэтому он включается по желанию для каждого события. update_calendar_event следует той же защите, что и update_draft: флаг применяется только когда вы также передаете новое description.

Настройка

cp signature-block.example.html signature-block.html   # then edit it
wrangler secret put SIGNATURE_HTML < signature-block.html
wrangler secret put SIGNATURE_LOGO_URL                 # paste your HTTPS logo URL

signature-block.html намеренно в .gitignore. Подпись — это конфигурация развертывания, а не исходный код: форк, унаследовавший закоммиченную подпись, отправлял бы письма с чужим именем, номером телефона и ссылками для бронирования. Закоммичен только плейсхолдер signature-block.example.html.

Токен __LOGO_URL__ внутри SIGNATURE_HTML заменяется на SIGNATURE_LOGO_URL во время выполнения.

Логотип должен быть публично доступен по HTTPS. Почтовые клиенты загружают его с машины получателя — у них нет доступа к вашей сети, привязкам вашего Worker или любым вашим учетным данным. Частный, аутентифицированный или localhost URL отображается как битое изображение для всех. Если SIGNATURE_LOGO_URL не задан, <img> полностью удаляется, а не выдает битый src.

Если SIGNATURE_HTML не задан, флаг является тихим no-op — письмо отправляется без подписи. Не настроенное развертывание никогда не вызывает ошибок.

Поведение

• Принудительный HTML. Подпись внутри текстового тела отображается как видимая сырая разметка, поэтому body_type переопределяется на html всякий раз, когда флаг установлен. Когда вы явно передали body_type: "text", переопределение сообщается в notes ответа инструмента, а не применяется молча.

• Текстовые тела экранируются, затем переводы строк становятся <br>, так что ваши переносы строк переживают принудительное переключение на HTML, а случайные символы < не могут стать разметкой.

• Идемпотентно. Если тело уже содержит подпись — распознается по собственному маркеру Worker или по отличительному тексту подписи — она не добавляется дважды.

• Ответы и пересылки размещают подпись над цитируемым оригиналом, а не внизу всей ветки.

• Пустое тело отправляет только подпись, без ведущих пустых строк.

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

Подпись добавляется после того, как тело вызывающего кода было санитизировано. Это намеренно и критически важно: sanitizeOutboundHtml удаляет каждый атрибут style= (XSS-вектор только через атрибуты), а подпись построена полностью из инлайн-стилей, поэтому пропуск через санитайзер удалил бы размер логотипа, разделитель и кнопки CTA.

Эти две строки имеют разные уровни доверия. Тело предоставлено агентом и недоверенно, поэтому оно по-прежнему полностью санитизируется. Подпись — это конфигурация развертывания, заданная оператором через wrangler secret put — любой, кто может установить этот секрет, уже может полностью изменить Worker. См. src/signature.ts.

Локальная разработка

cp .dev.vars.example .dev.vars   # fill in MCP_APPROVAL_CODE + MICROSOFT_CLIENT_SECRET; .dev.vars is gitignored
npm test                          # 171 tests via vitest with workers pool
npm run typecheck                 # tsc --noEmit
npm run dev                       # wrangler dev — local at http://localhost:8787

Эндпоинты

• GET /.well-known/oauth-authorization-server — метаданные OAuth (публично)

• GET /.well-known/oauth-protected-resource — метаданные ресурса (публично)

• GET /authorize — страница ввода кода подтверждения (публично)

• POST /approve — отправка кода подтверждения (с ограничением частоты)

• POST /token — обмен OAuth-токена (с ограничением частоты)

• POST /register — динамическая регистрация клиента по RFC 7591 (с ограничением частоты)

• GET /oauth/start — начало OAuth-потока Microsoft (ограничено MCP_APPROVAL_CODE)

• GET /oauth/callback — целевой адрес перенаправления OAuth Microsoft

• GET /oauth/status — проверка состояния подключения (ограничено MCP_APPROVAL_CODE)

• POST /mcp — диспетчеризация инструментов JSON-RPC (защищено bearer-токеном, с ограничением частоты)

Стек

• Cloudflare Workers (compatibility_date 2025-04-28, nodejs_compat)

• TypeScript (строгий режим)

• Hono v4

• Zod v4

• Vitest с @cloudflare/vitest-pool-workers (171 тест)

• @bashco/mcp-toolkit — общая обвязка для OAuth/криптографии/ограничения частоты/диспетчеризации

Ключевые аспекты архитектуры безопасности

• Двухпроходный санитайзер HTML с нормализацией сущностей в исходящих предпросмотрах писем

• Защита от SSRF с нормализацией 32-битных IP-адресов в исходящих HTTP-запросах

• Разбор конверта ошибок odata Microsoft Graph для структурированных ответов об ошибках

• Пофайловые инструменты по доменам в src/tools/ (почта, календарь, контакты, задачи, файлы, встречи, настройки) для удобства аудита

Непрерывное развёртывание

.github/workflows/deploy.yml запускает vitest run при каждом пуше в main, после чего выполняет развёртывание в Cloudflare. Чтобы включить на своём форке, задайте два секрета репозитория:

• CLOUDFLARE_API_TOKEN — создайте на dash.cloudflare.com/profile/api-tokens (используйте шаблон «Edit Cloudflare Workers»)

• CLOUDFLARE_ACCOUNT_ID — найдите в правом нижнем углу панели управления Cloudflare

Участие в разработке

Баг-репорты и pull request приветствуются на github.com/doublebash/outlook-mcp.

По изменениям в базовом коде OAuth/криптографии/ограничения частоты — инструментарий находится на github.com/doublebash/mcp-toolkit; баг-репорты оставляйте там.

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

Нашли уязвимость? Пожалуйста, не открывайте публичный issue. Оформите частное уведомление о безопасности на GitHub.

Лицензия

MIT — Copyright (c) 2026 Bashar Basheer.