@chrischall/office-outlook-mcp 0.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "office-outlook-mcp",
+  "owner": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "metadata": {
+    "description": "MCP server for Outlook / Microsoft 365 — mail, calendar, contacts and tasks via natural language",
+    "version": "0.0.0"
+  },
+  "plugins": [
+    {
+      "name": "office-outlook-mcp",
+      "displayName": "Outlook (Microsoft 365)",
+      "source": "./",
+      "description": "MCP server for Outlook / Microsoft 365 — read mail, folders, calendar, contacts and tasks, and send mail with confirmation",
+      "version": "0.0.0",
+      "author": { "name": "Chris Hall" },
+      "homepage": "https://github.com/chrischall/office-outlook-mcp",
+      "repository": "https://github.com/chrischall/office-outlook-mcp",
+      "license": "MIT",
+      "keywords": ["outlook", "office365", "microsoft365", "email", "calendar", "mcp"],
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "office-outlook-mcp",
+  "displayName": "Outlook (Microsoft 365)",
+  "version": "0.0.0",
+  "description": "Outlook / Microsoft 365 for Claude — read mail, folders, calendar, contacts and tasks, and send mail with confirmation, using your signed-in browser session",
+  "author": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "homepage": "https://github.com/chrischall/office-outlook-mcp",
+  "repository": "https://github.com/chrischall/office-outlook-mcp",
+  "license": "MIT",
+  "keywords": ["outlook", "office365", "microsoft365", "email", "calendar", "mcp"],
+  "skills": "./skills/",
+  "mcp": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/bundle.js"],
+      "env": {
+        "OUTLOOK_ACCESS_TOKEN": "${OUTLOOK_ACCESS_TOKEN}"
+      }
+    }
+  }
+}

package/README.md

@@ -0,0 +1,106 @@
+# office-outlook-mcp
+
+MCP server for **Outlook / Microsoft 365** — mail, folders, calendar, contacts
+and tasks, with confirm-gated sending.
+
+> This project was developed and is maintained by AI (Claude Code). Use at your
+> own discretion.
+
+## How it authenticates
+
+Outlook Web holds its access token in memory and sends it as
+`Authorization: Bearer …`. This server snapshots that header from your
+signed-in browser tab through the [fetchproxy](https://github.com/chrischall/fetchproxy)
+bridge, then talks to `https://outlook.office.com/api/v2.0` with ordinary
+server-side requests.
+
+**The browser is needed only to mint the token (~25h), never to make a call.**
+That is the whole design: no Azure app registration, no admin consent, and no
+browser on the request path.
+
+Tokens are cached at `~/.office-outlook-mcp/token.json` (0600), so a restart
+does not re-capture.
+
+## Install
+
+```sh
+npm i -g @chrischall/office-outlook-mcp
+```
+
+Requires the **Transporter** Chrome extension and `@fetchproxy/cli`, on a
+matching major version:
+
+```sh
+npm i -g @fetchproxy/cli
+```
+
+The first capture prints a 6-digit pair code to approve in the Transporter
+popup; the grant persists.
+
+### Configuration
+
+Everything is optional — with nothing set, the server captures from the browser.
+
+| variable | purpose |
+| --- | --- |
+| `OUTLOOK_ACCESS_TOKEN` | Pre-obtained bearer token. Overrides the bridge. Power users / CI only; expires in ~25h and **cannot be auto-refreshed**. |
+| `OUTLOOK_DISABLE_FETCHPROXY` | `1` to disable browser capture, requiring `OUTLOOK_ACCESS_TOKEN`. |
+| `OUTLOOK_API_BASE` | Override the REST base URL. Defaults to `https://outlook.office.com/api/v2.0`. |
+| `OUTLOOK_WS_PORT` | fetchproxy concentrator port. Defaults to `37149`, the fleet-wide shared port. |
+| `OUTLOOK_CAPTURE_TIMEOUT` | Seconds to wait for the tab to make a readable request. Defaults to `30`. |
+| `OUTLOOK_TOKEN_CACHE` | `false` to stop caching the token between runs. |
+| `OUTLOOK_TOKEN_FILE` | Path to the cached token. Defaults to `~/.office-outlook-mcp/token.json`. |
+
+## Tools
+
+**Read** — `outlook_list_folders`, `outlook_list_messages`,
+`outlook_get_message`, `outlook_list_attachments`, `outlook_list_events`,
+`outlook_get_event`, `outlook_list_calendars`, `outlook_get_profile`,
+`outlook_get_mailbox_settings`, `outlook_list_contacts`, `outlook_list_people`,
+`outlook_list_tasks`
+
+**Write** (all require `confirm: true`) — `outlook_send_mail`,
+`outlook_create_draft`, `outlook_mark_read`, `outlook_move_message`,
+`outlook_create_event`
+
+**Diagnostics** — `outlook_healthcheck`
+
+Every read tool takes `view: compact | full | raw`, defaulting to **compact**.
+Mutating tools make **no network call** without `confirm: true` — they return a
+dry-run preview of exactly what would be sent.
+
+## Things worth knowing
+
+- Fields are **PascalCase** (`ReceivedDateTime`, `IsRead`). This is the Outlook
+  REST API, not Graph — a Graph snippet silently returns nothing.
+- `outlook_get_message` returns a **plain-text** body by default, measured 9.4×
+  smaller than the HTML; pass `html: true` for the original.
+- `outlook_list_events` uses the calendar *view*, which expands recurring
+  series. `/me/events` does not, which is why it is not exposed as-is.
+- Time zones are **Windows** names (`Eastern Standard Time`), not IANA.
+- `search` and `unreadOnly` cannot be combined; the API rejects `$search`
+  alongside `$filter`, so the tool refuses before making a doomed request.
+- Moving a message assigns it a **new id**.
+
+## The lightweight alternative
+
+If you only need Outlook access from Claude Code on this machine, the
+`skills/outlook-fpx` access skill in this repo does the same reads with `fpx` +
+`curl` and no server at all. The MCP earns its keep when you want typed tools,
+confirm-gated writes, or reach from claude.ai.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test              # typecheck + suite
+npm run test:coverage # CI's gate
+```
+
+Request shapes are pinned in [`docs/OUTLOOK-API.md`](docs/OUTLOOK-API.md), all
+verified against a live mailbox.
+
+## License
+
+MIT

package/dist/auth-fetchproxy.js

@@ -0,0 +1,166 @@
+/**
+ * Bootstrap-only fetchproxy auth.
+ *
+ * Outlook Web holds its access token in JS memory and sends it as
+ * `Authorization: Bearer …` on every API call. We snapshot that header off a
+ * request the page already makes, and from then on this MCP talks to
+ * `https://outlook.office.com/api/v2.0` with a plain Node `fetch`.
+ *
+ * The bridge is therefore touched ONCE per token (~25h), never in the hot path.
+ * That is what makes this repo hostable: a full-bridge MCP needs a browser
+ * attached for every call, this one needs it only to mint.
+ *
+ * Verified live 2026-09-20 against a real M365 mailbox:
+ *   - the signed-in tab is on `outlook.cloud.microsoft` (the new Outlook Web
+ *     domain), but the token it carries has `aud: https://outlook.office.com`;
+ *   - that token authenticates plain server-side requests to
+ *     `outlook.office.com/api/v2.0` with no bridge involved;
+ *   - older tenants still serve the app from `outlook.office.com`, so both
+ *     hosts are declared and captured concurrently.
+ *
+ * We do NOT try to mint a token by calling an endpoint ourselves. There is no
+ * such endpoint reachable from the page's origin — the token comes from MSAL's
+ * hidden-iframe flow against login.microsoftonline.com, which a bridge fetch
+ * cannot drive. Capture is the only path, which is why a failed capture is a
+ * hard error with actionable guidance rather than a fallback.
+ */
+import { createBootstrapOpts, createFetchproxyTransport, } from '@chrischall/mcp-utils/fetchproxy';
+import { readPortEnv, readTtlMsEnv } from '@chrischall/mcp-utils';
+import { PACKAGE_NAME, VERSION } from './version.js';
+/**
+ * The fetchproxy concentrator port.
+ *
+ * ONE port for the whole fleet: the Transporter extension dials this port and
+ * servers host/peer-elect on it, so a "unique" per-MCP default would simply
+ * never be found. `OUTLOOK_WS_PORT` overrides it for local development and —
+ * the reason it exists — for a hosted bridged registration, where mcp-host
+ * names this variable in `bridgePortEnv` and puts the child's port in it.
+ *
+ * `readPortEnv` rather than `Number(...)` because the value arrives from a host
+ * template: an unsubstituted `${OUTLOOK_WS_PORT}` falls back to the default
+ * instead of handing `NaN` to the server.
+ */
+const DEFAULT_WS_PORT = 37_149;
+export function getWsPort() {
+    return readPortEnv('OUTLOOK_WS_PORT', DEFAULT_WS_PORT);
+}
+/** New Outlook Web. This is where a current tenant's tab actually lives. */
+const CAPTURE_DECL_CLOUD = {
+    host: 'outlook.cloud.microsoft',
+    path: '/*',
+    headerName: 'authorization',
+};
+/** Legacy host, still serving the app for tenants not yet migrated. */
+const CAPTURE_DECL_OFFICE = {
+    host: 'outlook.office.com',
+    path: '/*',
+    headerName: 'authorization',
+};
+/**
+ * How long to wait for the page to make a request we can read.
+ *
+ * The window IS the mechanism: capture resolves on the NEXT matching request,
+ * so nothing the page did before the listener came up counts. Outlook Web polls
+ * on its own, but an idle background tab can stay quiet for a while — 30s is
+ * long enough that ordinary polling or a user glance lands inside it, short
+ * enough that an idle tab does not hang a tool call for minutes.
+ */
+const CAPTURE_TIMEOUT_MS = readTtlMsEnv('OUTLOOK_CAPTURE_TIMEOUT', 30_000);
+/**
+ * The transport-wide deadline, derived from the capture window rather than left
+ * at the library default.
+ *
+ * `captureRequestHeader`'s own `timeoutMs` is silently capped by
+ * `fetchTimeoutMs`: a window raised past the deadline fails early at the
+ * deadline's number, which reads as a timeout nobody configured. Deriving it
+ * means the two cannot disagree.
+ */
+const BRIDGE_DEADLINE_MS = Math.max(CAPTURE_TIMEOUT_MS + 15_000, 30_000);
+/**
+ * Shortest plausible token. Real ones are ~5 KB of JWT; this only guards
+ * against an empty or echoed header, not against a wrong-audience token.
+ */
+const MIN_TOKEN_LENGTH = 100;
+/**
+ * Add `fetch` to the derived capability set.
+ *
+ * `createBootstrapOpts` infers capabilities from the bootstrap DECLARATIONS and
+ * the field REPLACES the server's defaults rather than extending them, so a
+ * declaration-only set can silently lose `fetch`.
+ */
+function withFetch(opts) {
+    const derived = opts.capabilities ?? [];
+    return {
+        ...opts,
+        capabilities: derived.includes('fetch')
+            ? derived
+            : [...derived, 'fetch'],
+    };
+}
+/** Normalise a captured header to a bare token, dropping any `Bearer ` prefix. */
+export function stripBearer(raw) {
+    const m = /^\s*Bearer\s+(.+)$/i.exec(raw);
+    return (m ? m[1] : raw).trim();
+}
+/**
+ * Capture an Outlook access token from the user's signed-in browser tab.
+ *
+ * Both hosts are raced: whichever the tab is actually on answers first, and the
+ * other simply never resolves. Returns the bare token (no `Bearer ` prefix).
+ */
+export async function captureTokenViaFetchproxy() {
+    const transport = createFetchproxyTransport({
+        ...withFetch(createBootstrapOpts({
+            domains: ['cloud.microsoft', 'office.com'],
+            bootstrap: {
+                captureHeaders: [{ ...CAPTURE_DECL_CLOUD }, { ...CAPTURE_DECL_OFFICE }],
+            },
+        })),
+        port: getWsPort(),
+        fetchTimeoutMs: BRIDGE_DEADLINE_MS,
+        serverName: PACKAGE_NAME,
+        version: VERSION,
+    });
+    try {
+        // `start()` loads the identity keypair. It does not bind the port or dial —
+        // that stays lazy until the first verb — but skipping it makes the first
+        // verb throw "ensureConnected called before listen()", which reads exactly
+        // like a pairing problem and is not one.
+        await transport.start();
+        const attempts = [CAPTURE_DECL_CLOUD, CAPTURE_DECL_OFFICE].map((decl) => transport.server
+            .captureRequestHeader({ ...decl, timeoutMs: CAPTURE_TIMEOUT_MS })
+            .then((raw) => {
+            if (typeof raw !== 'string') {
+                throw new Error(`${decl.host}: capture returned no header`);
+            }
+            const token = stripBearer(raw);
+            if (token.length < MIN_TOKEN_LENGTH) {
+                throw new Error(`${decl.host}: authorization header was present but too short to be a ` +
+                    `token (${token.length} chars)`);
+            }
+            return token;
+        }));
+        // `any` resolves on the first SUCCESS rather than the first settle, so the
+        // host the user is not on failing does not sink the one they are on.
+        try {
+            return await Promise.any(attempts);
+        }
+        catch (e) {
+            const detail = e instanceof AggregateError
+                ? e.errors.map((x) => x.message).join('; ')
+                : e.message;
+            throw new Error(`could not capture an Outlook token from the browser (${detail}). ` +
+                'Open a signed-in Outlook tab (outlook.cloud.microsoft or ' +
+                'outlook.office.com), leave it in the foreground for a moment so the ' +
+                'page makes a request, and retry.');
+        }
+    }
+    finally {
+        try {
+            await transport.close();
+        }
+        catch {
+            /* the token, or the original failure, is what matters */
+        }
+    }
+}