Skip to content

About

Read-only local MCP bridge to classic Outlook via COM (no Entra ID, no Graph)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

outlook-bridge

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.

Why

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.

Guarantees

  • Read-only, enforced by a test. tests/test_readonly_guard.py scans src/ 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.

MCP tools

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

Usage

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 export

The 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.

Architecture

  • gateway.py defines the OutlookGateway protocol. Only com_gateway.py touches 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.Bridge is 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 Restrict silently returns wrong results with ISO dates, pywin32 labels local wall-clock times as UTC, short-term EntryIDs from Table, Exchange senders, recurring series sharing one EntryID.

Development

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.

License

MIT

About

Read-only local MCP bridge to classic Outlook via COM (no Entra ID, no Graph)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages