Outlook MCP: Connecting to Outlook without 3rd-party auth

Unofficial local MCP server that drives Outlook the same way Outlook Web itself does — the first-party device-code flow plus Outlook Web's internal JSON API. No Microsoft Graph, no Azure app registration, no admin consent, no browser cookies, no desktop COM. Run it locally, connect any MCP client, and your agent can read, search, index and draft mail — sending only happens with a human-issued one-time approval for the exact content.

What it does

17 tools, stdio-only. Sending requires a one-time nonce issued by the human in a terminal (outlook-web-mcp approve <draftId>); the digest binds the exact HTML body, recipients, Bcc and attachments, and expires in 30 minutes.

Related MCP server: outlook-web-mcp-server

Why no third-party auth

Microsoft Graph and most Outlook integrations require an Azure app registration and tenant admin consent — a wall if you are on a managed account. This fork instead signs in through Outlook Web's own first-party client ID with the device-code flow, then speaks the same private JSON dialect the web app speaks. Nothing asks an admin for anything.

Quickstart

# clone, then:
uv sync --locked
uv run outlook-web-mcp doctor    # local health check, no network, no secrets
uv run outlook-web-mcp login     # device-code sign-in with Outlook's own client id

Register in your MCP client (e.g. claude mcp add / settings.json):

{
  "mcpServers": {
    "outlook-web": {
      "command": "/absolute/path/to/onezion-outlook-web-mcp/.venv/bin/outlook-web-mcp-server",
      "env": { "OUTLOOK_WEB_TIME_ZONE_ID": "China Standard Time" }
    }
  }
}

The send gate

1. Agent calls create_draft / create_reply_draft — saved to Drafts, never sent.

2. You review it in Outlook, then run outlook-web-mcp approve <draftId> in a terminal. It prints exactly what you are approving and writes a one-time nonce.

3. Agent calls send_draft — it sends only if the nonce matches the exact content (digest covers HTML body, To/Cc/Bcc, attachment name:size) and is within 30 minutes. Editing anything invalidates the approval; the nonce is consumed on send. Never run approve for an agent, and never paste a nonce into a chat.

Security posture

• CA bundle pinned to certifi; trust_env=False so environment proxies cannot hijack token-bearing requests (explicit proxy opt-in only).

• Upstream error text is never echoed to tool results; opt-in logs are 0600.

• Response size cap enforced mid-stream; every response must come from the pinned OWA host.

• Stored credentials are refused if the client id changes; verification URLs must be a Microsoft sign-in host.

• Full findings ledger: docs/audit/2026-11-06-security-audit.md (P2 7/7 closed).

Docs

• PITFALLS.md — 23 hard-won pitfalls of this private dialect (flat recipient entries, SendItem 500, ItemClass vs MessageClass, …). Read before hacking.

• docs/specs/ docs/plans/ docs/acceptance-*.md — dated design/acceptance trail.

• docs/audit/2026-11-06-security-audit.md — third-party-style audit + closure ledger.

• skills/use-outlook-web-mcp/ — an agent-facing skill (MCP copy; runbook for JS-rendered mail is screenshot + OCR outside the MCP).

• docs/internal-api.md — upstream's dialect notes.

Credits & license

Fork of ma-nakaya/outlook-web-mcp-server (see NOTICE, upstream pin aa41b13). Upstream code stays MIT; all fork modifications are licensed under AGPL-3.0 — any hosted modification of this server must publish its source. See LICENSE for the exact boundary. Maintainer: onezion12344. Not affiliated with Microsoft or the upstream author.

Status

Tested against one real Exchange Online tenant (HKU) with ~12k messages indexed. CI matrix configured (ubuntu/macOS/Windows); the collector under collector/pixel-worker/ is deployable but not deployed, and read-tracking pixels are therefore off unless you deploy it yourself.