Skip to main content
Glama
outlook-bridge

outlook-bridge

by PhamHoang16

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

Result

Meaning

Action

com_ok: True, inbox_count returns a number

COM path is working

Ready to register the MCP server

com_ok: False + mentions New Outlook / GPO

This architecture cannot be used on that machine

Stop — no fallback plan (risk R2 below)

com_ok: True, index_ok: False

Still usable, but body-content search will fall back to sequential scanning (slower, with a warning in results)

Use normally

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

Available Tools

5 tools
get_threadA

Lấy toàn bộ mail trong cùng luồng hội thoại, sắp từ cũ tới mới.

Inputs: mail_id (required), limit. Returns: result

list_foldersA

Liệt kê cây folder của Outlook kèm số item và số mail chưa đọc.

Inputs: no named parameters. Returns: result

read_attachmentA

Trích text từ một tệp đính kèm. ref là tên tệp hoặc chỉ số từ read_mail. Hỗ trợ txt/csv/md/json/xml/pdf/xlsx/docx.

Inputs: ref (required), mail_id (required), max_chars. Returns: result

read_mailA

Đọc nội dung đầy đủ của 1-10 mail theo handle từ search_mail. Liệt kê tên tệp đính kèm nhưng KHÔNG đọc nội dung tệp — dùng read_attachment cho việc đó.

Inputs: ids (required), max_body_chars. Returns: result

search_mailA

Tìm mail. Trả danh sách gọn kèm handle (h1, h2...) để dùng cho read_mail. query tìm trong nội dung mail; folder="*" tìm mọi folder. Ngày theo định dạng YYYY-MM-DD.

Inputs: limit, query, since, until, +7 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct aspect: thread retrieval, attachment extraction, individual mail reading, folder listing, and search. No two tools overlap in purpose, and the descriptions clarify the boundaries (e.g., read_mail vs get_thread).

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case: get_thread, read_attachment, read_mail, list_folders, search_mail. The verbs are specific and predictable.

    Tool Count5/5

    Five tools is well-scoped for an email read/search bridge. Each tool serves a clear, non-redundant function in the core workflow of finding and reading emails with attachments.

    Completeness5/5

    The tool surface covers the full read/search lifecycle: search returns handles, read_mail consumes them, get_thread expands conversations, list_folders scopes searches, and read_attachment handles file content. No obvious missing operations for the apparent read-only purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Microsoft Outlook emails, calendar events, contacts, and folders via COM automation.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to read, send, and manage Outlook mail locally on Windows via COM/MAPI, without cloud APIs.
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Reads and searches your local Microsoft Outlook desktop mailbox via COM, supporting folder listing, message/thread retrieval, attachment saving, bulk export, and draft creation without sending, requiring no OAuth or admin consent.
      -