A read-only, fully local bridge between classic desktop Outlook and Claude. It reads mail, meetings and calendars through COM (pywin32), with no Entra ID app registration, no Microsoft Graph and no OAuth.
One Python core serves three front ends:
- a CLI (
outlook-bridge) for quick lookups in the terminal; - an MCP server over stdio (
outlook-bridge-mcp) with 9 tools for Claude Code or Claude Desktop; - snapshot exports (JSON and Markdown) to a synced folder.
The official Microsoft 365 connector needs an app registered in the tenant. Many corporate and school accounts don't allow that. Classic Outlook already holds the data locally, and COM can read it without any network call. This project explores MCP, COM and packaging Claude extensions from a base I control end to end.
- Read-only, enforced by a test.
tests/test_readonly_guard.pyscanssrc/and fails on any call that could change a mailbox (.Send(,.Delete(,.Move(,.Save(,.Reply(,CreateItem(…) and on any COM property assignment. Not even the "read" flag is written. - Untrusted content is labelled. Every field that comes from a mail or an event is returned with
untrusted_content: true, and the tool descriptions remind the model that it is data, never instructions (a known prompt-injection path). - Exclusions apply everywhere, even by ID. Accounts, folders, senders, subject keywords and redaction
regexes from
config.toml(French IBANs are masked by default). - No network, no telemetry. The audit log records the tool, its parameters, the result count and the duration, never a subject or a body.
- Synthetic fixtures only. No real mail data in tests, logs or commits.
| Tool | Purpose |
|---|---|
status |
Outlook reachable, accounts, configuration in effect |
list_accounts, list_folders |
Mailbox structure |
search_mail |
Mails by date range, sender, subject, folder, unread… |
get_mail, get_thread |
One mail (body capped) or a whole conversation |
list_events, get_event |
Meetings across calendars, recurrences expanded |
find_free_slots |
Free slots within working hours |
Requirements: Windows, classic Outlook (the new Outlook has no COM), Python 3.12+ and uv.
uv sync
uv run outlook-bridge status
uv run outlook-bridge mails --help # dates accept 2d, +7d, auj, 16/10, 14:00
uv run outlook-bridge events
uv run outlook-bridge slots
uv run outlook-bridge exportThe MCP server is declared for Claude Code in .mcp.json (uv run outlook-bridge-mcp). Configuration lives in
%APPDATA%\outlook-bridge\config.toml; start from config.example.toml.
gateway.pydefines theOutlookGatewayprotocol. Onlycom_gateway.pytouches COM, on a single STA worker thread with a request queue, so no COM object crosses threads.- All logic (DASL/Jet filters, time zones, recurrences, exclusions, redaction, free slots) lives in plain
modules (
mail.py,events.py,redact.py,timeutil.py) and is tested against a fake gateway, without Outlook. core.Bridgeis the single entry point. The CLI, the MCP server and the exporter are thin layers that return pydantic models (models.py).- COM pitfalls handled explicitly: Jet
Restrictsilently returns wrong results with ISO dates, pywin32 labels local wall-clock times as UTC, short-term EntryIDs fromTable, Exchange senders, recurring series sharing one EntryID.
uv run pytest # unit tests (fake gateway, no Outlook needed)
uv run pytest -m outlook # integration tests against a real Outlook
uv run ruff check . && uv run ruff format .The project was built in phases with Claude Code from a written specification
(OUTLOOK_BRIDGE_SPEC.md, in French), with a checkpoint and a report after each phase
(docs/). I wrote the specification and the safety rules, then reviewed and validated every phase.