outlook-mcp-server

Локальный MCP сервер, который даёт Claude (Desktop или Code) доступ на чтение/запись к личной почте Hotmail / Outlook.com через Microsoft Graph API, используя поток авторизационного кода OAuth 2.0 (с PKCE) против платформы удостоверений Microsoft.

Он предоставляет шесть инструментов: list_messages, get_message, search_messages, send_message, create_draft и list_folders.

Всё выполняется локально через stdio — здесь нет размещённого сервиса, и ваша почта никогда не проходит ни через что, кроме вашей машины и собственного Graph API Microsoft.

Как это работает

• Аутентификация: MSAL Node выполняет поток авторизационного кода + PKCE против https://login.microsoftonline.com/consumers (только личные учётные записи — см. Выбор арендатора), используя кратковременный локальный HTTP-сервер как цель перенаправления. Токеры (включая refresh-токен offline_access) кэшируются и незаметно обновляются при последующих запусках.

• Хранилище: кэш токенов сериализуется MSAL, шифруется AES-256-GCM с локально сгенерированным ключом и записывается в ~/.outlook-mcp-server/token-cache.enc (режим 0600). Сам ключ находится в ~/.outlook-mcp-server/cache.key (также 0600). См. замечания по безопасности относительно модели угроз, которую это (не) покрывает.

• Вызовы Graph: тонкий Fetch-клиент вызывает https://graph.microsoft.com/v1.0/... с текущим токеном доступа.

• MCP-сервер: построен на @modelcontextprotocol/sdk, говорит через stdio, поэтому может быть запущен непосредственно Claude Desktop / Claude Code как дочерний процесс.

Related MCP server: Outlook MCP Python

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

• Node.js 18+

• Учётная запись Microsoft (Hotmail, Outlook.com или Live) — почтовый ящик, к которому Claude должен получить доступ.

• Бесплатная Azure-учётная запись для регистрации приложения допуска, он не должен быть платной подпиской Azure.

1. Установка

git clone <this repo>
cd outlook-mcp-server
npm install

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

Эта регистрация выдаёт идентификатор клиента, который этот сервер использует для доступа к Microsoft Graph от вашего имени. npm run setup (ниже) проведёт вас через это интерактивно, но шаги такие:

1. Перейдите на portal.azure.com и войдите с любой учётной записью Microsoft.

2. Найдите Регистрации приложений → + Новая регистрация.

3. Заполните форму:

   • Имя: любое, например outlook-mcp-server.

   • Поддерживаемые типы учётных записей: «Только личные учётные записи Microsoft». Это ограничивает приложение учётными записями Hotmail/Outlook.com/Live, а не рабочими/учебными (Azure AD) арендаторами.

   • URI перенаправления: платформа «Публичный клиент/нативный (мобильные и настольные)», значение http://localhost:8765/callback (или другой порт — просто будьте последовательны, когда скрипт настройки спросит).

4. Нажмите Зарегистрировать, затем скопируйте Идентификатор приложения (клиента) на странице обзора.

5. Перейдите в Разрешения API → + Добавить разрешение → Microsoft Graph → Делегированные разрешения и добавьте:

   • Mail.Read

   • Mail.ReadWrite

   • Mail.Send

   • offline_access (часто присутствует по умолчанию)

   Делегированные разрешения для личных учётных записей Microsoft не требуют согласия администратора — вы сами согласитесь при входе в шаге 3 ниже.

6. (Необязательно, дополнительно) Если вы предпочитаете использовать конфиденциальный клиент с секретом клиента вместо потока PKCE для публичного клиента, добавьте платформу Web с URI перенаправления и создайте секрет в разделе Сертификаты и секреты. Большинству людей следует пропустить этот шаг.

3. Настройка (аутентификация + конфигурация)

npm run setup

Это:

1. Выведет приведённый выше пошаговый инструктор.

2. Запросит идентификатор клиента (и необязательный секрет / аренду / URI перенаправления) и сохранит его в ~/.outlook-mcp-server/config.json.

3. Откроет браузер для входа и согласия.

4. Проверит, что токен работает, вызвав GET /me и напечатав ваше имя/почту.

5. Выведет JSON-фрагмент для добавления в вашу конфигурацию Claude (см. ниже).

Позже вы сможете пройти аутентификацию заново (отозванный токен, смена аккаунта и т.д.) без повторного ввода данных регистрации приложения:

npm run login

4. Сборка и регистрация в Claude

npm run build

Claude Desktop — добавьте в claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json на macOS, %APPDATA%\Claude\claude_desktop_config.json на Windows):

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-mcp-server/dist/src/index.js"]
    }
  }
}

Claude Code:

claude mcp add outlook -- node /absolute/path/to/outlook-mcp-server/dist/src/index.js

Перезапустите Claude Desktop / Claude Code. Нижеописанные инструменты должны стать доступны.

Инструменты

Все инструменты возвращают JSON (как текстовое содержимое MCP) и при ошибках Graph API возвращают ошибки инструмента вместо краха сервера.

Выбор аренды

По умолчанию используется тенант consumers (https://login.microsoftonline.com/consumers), который принимает только личные учётные записи Microsoft (Hotmail/Outlook.com/Live) — рабочая или учебная учётная запись будет отклонена при входе. Если нужно поддерживать и личные, и Azure AD учётные записи, задайте тенант как common во время npm run setup (или через OUTLOOK_MCP_TENANT=common). Этот проект разработан и протестирован для случая личных учётных записей (consumers).

Этот проект.

Справочник по конфигурации

Всё можно задать через npm run setup (записывается в ~/.outlook-mcp-server/config.json) или через переменные окружения, которые имеют приоритет — см. .env.example:

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

• the token cache is encrypted at rest with a locally-generated AES-256-GCM key (~/.outlook-mcp-server/cache.key, mode 0600). This protects against casual disclosure — accidental commits, backups, other unprivileged users on a shared machine — but not against an attacker who already has read access to your user account's files, since the key sits next to the encrypted cache. For stronger protection, swap the ICachePlugin in src/auth/tokenCache.ts for one backed by your OS keychain (e.g. via keytar) — the plugin interface is intentionally isolated to that one file.

• Never commit ~/.outlook-mcp-server/ (it's outside the repo by default) or a .env file containing OUTLOOK_MCP_CLIENT_SECRET.

• send_message sends immediately with no confirmation step inside this server — Claude is expected to confirm intent with you before calling it for anything sensitive. Prefer create_draft when you want a review step.

• Requested scopes are limited to Mail.Read, Mail.ReadWrite, Mail.Send, and offline_access — no calendar, contacts, or broader Mail.* application-level access.

Troubleshooting

• AADSTS50020 / “user account ... does not exist in tenant” — you're hitting a tenant that doesn't accept personal accounts, or you're signing in with a work/school account against consumers. Confirm the app registration's “Supported account types” is “Personal Microsoft accounts only” and OUTLOOK_MCP_TENANT is consumers (or common if you intentionally want both).

• AADSTS50011 / redirect URI mismatch — the redirectUri in ~/.outlook-mcp-server/config.json must exactly match a redirect URI configured on the Azure app registration, including the port.

• “Not signed in” tool errors — run npm run login.

• Port already in use during setup/login — another process is using the redirect URI's port; stop it, or reconfigure the app registration and npm run setup with a different port.

Разработка

npm run dev     # run the MCP server directly from TypeScript (stdio)
npm run build   # compile to dist/
npm run clean   # remove dist/

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

src/
  index.ts            MCP server entrypoint (stdio transport)
  config.ts            Config loading (env + config file)
  auth/
    crypto.ts           AES-256-GCM file encryption helpers
    tokenCache.ts        MSAL ICachePlugin backed by crypto.ts
    msalClient.ts        MSAL app factory + silent token acquisition
    loginFlow.ts          Interactive loopback OAuth flow
  graph/
    client.ts            Generic Microsoft Graph fetch wrapper
    mail.ts               Mail-specific Graph calls
    types.ts              Graph response types
  tools/                 One file per MCP tool, registered in index.ts
scripts/
  setup.ts              Interactive one-time (and re-runnable) setup