mcp-outlook

Разворачиваемый у себя MCP-сервер для локального Microsoft Exchange через EWS (Exchange Web Services). Создан для сред с изоляцией от внешних сетей / без облака — он общается напрямую с вашим внутреним Exchange-сервером и никогда не обращается к Microsoft Graph, Azure AD или настольном клиенту Outlook.

• Бэкенд: exchangelib (клиент EWS)

• Фреймворк: FastMCP

• Транспорт: streamable-http (автономный HTTP-сервер, к которому подключаются другие внутренние хосты)

• Аутентификация в Exchange: basic или NTLM (выбирается через конфигурацию)

Два режима

Как режим jwt связывает идентичность. Exchange не может использовать JWT вашей компании (Outlook основан на PKINIT/Kerberos). Поэтому MCP выполняет два отдельных процесса аутентификации, которые никогда не смешиваются:

User --(JWT)--> MCP validates the token, reads the user's email
                MCP --(service account, NTLM)--> Exchange
                MCP --(impersonation header = user's email)--> acts on the user's mailbox

JWT пользователя никогда не отправляется в Exchange, и ни пароль пользователя, ни смарт-карта никогда не касаются MCP — только единственные учётные данные службы. О том, что администраторы должны настроить для режима jwt, см. TODO.md.

Related MCP server: OWA Exchange MCP Server

Инструменты

list_emails и search_emails также принимают unread_only=true, чтобы возвращать только непрочитанные сообщения.

Установка

Требуется Pythorn 3.11+ и uv.

uv sync                 # create venv + install deps
cp .env.example .env    # then edit .env with your Exchange details
uv run python -m mcp_outlook

Сервер привязывается к MCP_HOST:MCP_PORT (по умолчанию 127.0.0.1:8000) и обслуживает MCP-endpoинт streamable-http по адресу /mcp.

Локалное бета-тестирование (без настройки администратором)

Запустите с вашим собственным почтовым ящиком и вашими именем пользователя/паролем — без JWT, олицетворения, служебной учётной записи и смарт-карты:

# in .env:
OUTLOOK_AUTH_MODE=static          # the default
OUTLOOK_EWS_ENDPOINT=https://mail.corp.local/EWS/Exchange.asmx
OUTLOOK_USERNAME=CORP\you
OUTLOOK_PASSWORD=...
uv run python -m mcp_outlook

Конфигурация

Все настройки задаются через переменные окружения (или файл .env). Полный список см. в .env.example. Основное:

Поиск конечной точки EWS

URL EWS — это не URL OWA (веб-почты). На сервере Exchange:

Get-WebServicesVirtualDirectory | fl Name,InternalUrl,ExternalUrl

В изолированной (air-gapped) среде почти всегда нужен InternalUrl.

Тестирование

Модульные тесты не требуют сервера Exchange (только разбор конфигурации + сериализация):

uv run pytest

Живой смоук-тест (с реальным .env): запустите сервер, подключите MCP-клиент или MCP Inspector, затем вызовите list_folders → list_emails → send_email (себе) и подтвердите получение. Переключайте OUTLOOK_AUTH_TYPE между ntlm и basic, чтобы подтвердить тот вариант, который включён вашим администратором Exchange.

Интерфейс создания (MCP Apps)

draft_email открывает интерактивный виджет MCP Apps — React-композер, встроенный в один автономный HTML-файл (src/mcp_outlook/widgets/compose.html). Любой хост, поддерживающий MCP Apps, отображает его прямо в ветке чата.

Возможности виджета:

• Поле «Кому» со встроенным поиском контактов — после последней запятой начните вводить текст для поиска контактов; выберите результат, чтобы заменить запрос чипом; корректные адреса отображаются как подписанные чипы.

• Send / Discard — Send вызывает send_email прямо из виджета (только для приложения — модель не может его вызвать); Discard сворачивает карточку.

• Замещение — открытие нового черновика затемняет любой более старый открытый виджет черновика.

• Подпись — каждый черновик предварительно заполняется строкой "Written with Airchat" (можно редактировать).

Гарантия автономности (Air-gap): собранный HTML (React + встроенный bridge JS) поставляется с Python-пакетом. Во время выполнения не выполняется никаких внешних запросов ресурсов; Node.js нужен только для пересборки виджета.

Пересборка виджета (только для разработки)

cd frontend
npm ci
npm run build     # tsc + vite build + artifact copy → src/mcp_outlook/widgets/compose.html

Скрипт сборки перед копированием проверяет, что в HTML не попало внешних URL.

Попробуйте визуально (автономное превью для разработки)

cd frontend && npm run dev
# Opens http://localhost:5173 with a mock host — no Exchange needed.
# Type in To, see chips form, contact results appear, Send/Discard collapse the card.

Подводные камни

• Базовую аутентификацию часто отключают на современных Exchange — NTLM является более безопасным вариантом по умолчанию.

• Внутренние/самоподписанные сертификаты требуют OUTLOOK_CA_BUNDLE, иначе соединение не пройдёт проверку TLS.

• Многопользовательскому режиму (jwt) нужно одно разрешение Exchange — служебная учётная запись должна иметь роль RBAC ApplicationImpersonation. См. TODO.md. Режим static не требует такого разрешения.

• В .env хранится пароль в открытом виде. Он игнорируется git; также ограничьте права на файл (chmod 600 .env) на хосте.