outlook-mcp

Локальный MCP-сервер для работы с Outlook / Exchange mailbox через EWS SOAP API, NTLM, HTTP/1.1 и persistent keep-alive connection.

Сервер не вызывает LLM сам. Он предоставляет MCP tools и возвращает структурированные JSON-данные. Анализ, суммаризация и reasoning выполняются внешним MCP-клиентом: Cursor, Cline, Claude Desktop или другим совместимым клиентом.

Архитектура

MCP client
  ↓ stdio
outlook-mcp
  ↓ EWS SOAP + NTLM + HTTP/1.1
Exchange EWS
  ↓
Exchange mailbox

Tools зависят от MailService, а не от EWS напрямую. Сейчас реализован EwsMailService; позже можно добавить GraphMailService без переписывания MCP tools.

Когда использовать EWS

Этот сервер полезен для Exchange environments, где доступен EWS endpoint, но Microsoft Graph недоступен или не подходит: on-prem Exchange, hybrid deployments, legacy enterprise setups или environments с NTLM/Negotiate authentication.

Basic Auth не используется. Основной backend — EWS SOAP через NTLM over HTTP/1.1. Архитектура оставляет место для Graph backend позже.

Требования

• Node.js 20+
• Доступ к VPN или внутренней сети, если EWS endpoint не публичный
• Доступ к EWS URL
• Доменный пользователь
• NTLM-аутентификация

Ручная проверка EWS

Проверить endpoint:

curl -I https://mail.example.com/EWS/Exchange.asmx

Ожидаемо:

401 Unauthorized
WWW-Authenticate: NTLM
WWW-Authenticate: Negotiate

Проверить NTLM:

curl -v --http1.1 --ntlm -u 'DOMAIN\\username' https://mail.example.com/EWS/Exchange.asmx

Ожидаемо:

HTTP/1.1 200 OK
Persistent-Auth: true

Установка из npm

После публикации пакет можно запускать через npx:

npx -y @alexbuzo/outlook-mcp

Или установить глобально:

npm install -g @alexbuzo/outlook-mcp
outlook-mcp

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

git clone https://github.com/abuzo/outlook-mcp.git
cd outlook-mcp
npm install
npm run build
npm test

Настройка env

Скопируйте .env.example в .env и заполните:

MAIL_BACKEND=ews
EWS_URL=https://mail.example.com/EWS/Exchange.asmx
EWS_AUTH_TYPE=ntlm
EWS_DOMAIN=EXAMPLE
EWS_USERNAME=<domain-user>
EWS_PASSWORD=<ews-password>
[email protected]

Ключевые политики по умолчанию:

ALLOW_SEND=false
ALLOW_MOVE=false
ALLOW_MARK_READ=true
ALLOWED_SEND_DOMAINS=example.com

Если ALLOWED_SEND_DOMAINS пустой, отправка считается allow all только при ALLOW_SEND=true. Это рискованный режим; используйте его только осознанно.

Проверка EWS

npm run ews:ping
npm run ews:find-inbox

Запуск локально

npm run dev

npm run dev запускает MCP server на stdio. В MCP runtime stdout используется только для JSON-RPC протокола, все логи идут в stderr.

MCP config

Пример для Cursor/Cline/Claude Desktop при запуске опубликованного npm-пакета:

{
  "mcpServers": {
    "outlook-mcp": {
      "command": "npx",
      "args": ["-y", "@alexbuzo/outlook-mcp"],
      "env": {
        "MAIL_BACKEND": "ews",
        "EWS_URL": "https://mail.example.com/EWS/Exchange.asmx",
        "EWS_AUTH_TYPE": "ntlm",
        "EWS_DOMAIN": "EXAMPLE",
        "EWS_USERNAME": "<domain-user>",
        "EWS_PASSWORD": "<ews-password>",
        "MAILBOX_SMTP": "[email protected]",
        "ALLOW_SEND": "false",
        "ALLOW_MOVE": "false",
        "ALLOW_MARK_READ": "true",
        "ALLOWED_SEND_DOMAINS": "example.com"
      }
    }
  }
}

Пример для локального checkout:

{
  "mcpServers": {
    "outlook-mcp": {
      "command": "node",
      "args": ["/absolute/path/outlook-mcp/dist/index.js"],
      "env": {
        "MAIL_BACKEND": "ews",
        "EWS_URL": "https://mail.example.com/EWS/Exchange.asmx",
        "EWS_AUTH_TYPE": "ntlm",
        "EWS_DOMAIN": "EXAMPLE",
        "EWS_USERNAME": "<domain-user>",
        "EWS_PASSWORD": "<ews-password>",
        "MAILBOX_SMTP": "[email protected]",
        "ALLOW_SEND": "false",
        "ALLOW_MOVE": "false",
        "ALLOW_MARK_READ": "true",
        "ALLOWED_SEND_DOMAINS": "example.com"
      }
    }
  }
}

MCP tools

• search_emails — поиск писем без full body.
• read_email — чтение metadata и опционально body с ограничением размера.
• read_thread — чтение цепочки по conversationId.
• list_attachments — metadata вложений без скачивания binary content.
• extract_action_items — deterministic helper по простым русским и английским маркерам.
• create_draft — создание черновика, без отправки.
• create_reply_draft — создание reply/reply-all черновика, без отправки.
• send_draft — отправка только существующего draft при ALLOW_SEND=true и confirm=true.
• mark_as_read — установка read/unread при ALLOW_MARK_READ=true.
• move_email — перемещение в inbox, archive или deleteditems при ALLOW_MOVE=true.

Security notes

• Read-only by default: отправка и перемещение выключены.
• send_draft требует ALLOW_SEND=true и confirm=true.
• Permanent delete не реализован.
• Binary content вложений не скачивается.
• Пароль, NTLM challenge/response, Authorization headers, body писем и вложения не логируются.
• Audit log пишет timestamp, tool, action type, target id, success/failure и sanitized error.
• Body ограничивается MAX_BODY_CHARS.
• Количество результатов ограничивается MAX_SEARCH_RESULTS и MAX_THREAD_MESSAGES.
• Отправка проверяет recipients по ALLOWED_SEND_DOMAINS.
• TLS verification не отключается.

Troubleshooting

HTTP_1_1_REQUIRED

Причина: Exchange не принимает NTLM over HTTP/2. Решение: EWS_FORCE_HTTP1=true.

401 Unauthorized

Возможные причины:

• неверный EWS_DOMAIN;
• неверный EWS_USERNAME или EWS_PASSWORD;
• EWS недоступен для пользователя;
• VPN не подключен.

403 Forbidden

Возможные причины:

• политика Exchange запрещает EWS;
• mailbox недоступен для пользователя.

SELF_SIGNED_CERT / certificate issue

Не отключайте TLS verification без согласования. Проверьте корпоративный root CA в системном trust store.

MCP protocol broken

Причина: что-то пишет в stdout. В MCP runtime stdout должен содержать только JSON-RPC. Все logs, debug и startup errors должны идти в stderr.

node-libcurl install problems

На macOS обычно достаточно:

npm install

Если сборка native dependency не проходит:

xcode-select --install
brew install curl
npm install

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

• Нет скачивания вложений.
• Нет Microsoft Graph backend.
• Нет OAuth backend.
• Нет Kerberos/Negotiate backend.
• Нет shared mailbox impersonation.
• Нет UI.
• Нет автоматической отправки писем.
• Нет permanent delete.

Roadmap

• Graph backend.
• OAuth EWS backend.
• Kerberos/Negotiate backend.
• Shared mailbox support.
• Attachment download with policy.
• Secure password storage через macOS Keychain.
• Docker packaging.