outlook-bridge

MCP server for Claude to search and read mail in Outlook classic (Windows, via COM) — list_folders, search_mail, read_mail, get_thread, read_attachment. See the full design at docs/superpowers/specs/2026-08-24-outlook-bridge-design.md and the implementation plan at docs/superpowers/plans/2026-08-24-outlook-bridge-a.md.

Read-only — no write tools

This server does not have send_mail, delete_mail, move_mail, mark_as_read, or any tool that modifies/deletes/sends mail. No method in Win32MailStore calls .Send(), .Save(), .Delete(), .Move(), .MarkAsRead(), or assigns a value to any Outlook property. The only exception: read_attachment writes the attachment to a temporary directory the server creates itself (tempfile.TemporaryDirectory) to extract text, then deletes that directory right after — SaveAsFile is a read API, it does not modify anything in Outlook.

Related MCP server: outlook-mcp

Run on Linux (dev machine) — FakeMailStore

No Outlook needed, no Windows needed. FakeMailStore loads a YAML fixture (~50 synthetic mails: multiple folders, multiple stores, conversation threads, attachments of all kinds, Vietnamese mails, long-body mails, empty mails, non-mail items) and implements the same MailStore interface that Win32MailStore implements.

python -m venv .venv
.venv/bin/pip install -e ".[dev]"

# Chạy server với store giả (không cần Outlook)
OUTLOOK_BRIDGE_FAKE=1 OUTLOOK_BRIDGE_FIXTURE=tests/fixtures/mailbox.yaml \
  .venv/bin/python server.py

Running tests

Linux (most of the logic — pure Python + FakeMailStore):

.venv/bin/pytest

Windows (the contract test suite SHARED by both stores — this is the only way to prove that Win32MailStore actually matches FakeMailStore behavior, not just "runs"):

set OUTLOOK_BRIDGE_CONTRACT_WIN32=1
.venv\Scripts\pytest tests/contract -v

A few cases in this suite are intentionally SKIPped on a real mailbox (data only exists in the FakeMailStore fixture) — see the "Intentional test SKIPs" section in docs/WINDOWS-RUNBOOK.md before treating a SKIP as a sign of trouble.

See docs/INSTALL-windows.md to install and register the MCP server on Windows, and docs/WINDOWS-RUNBOOK.md for the sequence of steps to do when sitting in front of a real Windows machine for the first time.

Environment diagnostics — doctor.py

python doctor.py            # trên Linux: báo "không phải Windows", degrade an toàn
python doctor.py --verbose  # trên Windows: thêm chi tiết root.Name, cây folder, giá trị raw

Two risks no one has solved yet (spec §13)

R2 — New Outlook will gradually replace Outlook classic, and COM disappears with it. Microsoft is force-migrating users to New Outlook, which does not register a COM server (doctor.py reports com_ok: False when this happens). This is something with an expiration date, not a bug that can be patched. The only way out when it happens is to rewrite Win32MailStore on top of the Microsoft Graph API — the project's architecture (all COM details live in exactly two files, win32_store.py and doctor.py) limits the damage to rewriting exactly those two files, not the whole system.

R3 — Internal company mail content goes through Anthropic's API. COM runs entirely locally (nothing leaves the machine to read mail), but for Claude to answer based on mail content, that content must be sent to the API. This is an inherent trade-off of using an AI assistant to read mail — no server can solve it for you.

The only control measure: folder_allowlist in config.toml. Set it to a specific list of folders (store-qualified, e.g. "Mailbox - Nguyen Van A/Inbox") to limit the scope of mail this server can see — mail outside the allowlist cannot be read by any tool, through any call path (search, read by id, read thread, download attachment), even when a conversation thread crosses the allowlist boundary.

Matching is EXACT, not prefix-based. Allowing "Inbox" does NOT include "Inbox/Bao cao" — every folder you want to allow must be listed separately. This is a deliberate design choice, not a limitation: a prefix-based allowlist can easily let through a sensitive subfolder the person configuring it didn't think of. If folder_allowlist is not configured (default, empty list), every folder in the mailbox is readable — configure it before pointing this server at a real company mailbox. See step 2 of docs/WINDOWS-RUNBOOK.md for how to get the exact store-qualified folder names from list_folders.

If you need to tighten further: narrow folder_allowlist down to a few specific folders, or — if that's still not enough — consider returning only metadata + snippet instead of the full mail content (no tool does this yet; a new tool would be needed).