outlook-mcp: Instructions file for Claude Code

outlook-mcp

MCP server connecting Claude to a personal outlook.com mailbox through Microsoft Graph. One shared tool registry is served over two transports: a local stdio server (Node + MSAL, on-disk token cache) and a Cloudflare Worker that claude.ai adds as a custom connector. This repo is public. README.md is the tool surface and security model, SETUP.md the install from zero, CAPABILITIES.md the Outlook-parity audit — read those rather than restating them here.

Commands worth knowing

• npm run doctor — first thing to run when anything is broken; -- --env-only needs no credentials.
• npm run test:offline — no Graph, no KV, no secrets. The only tier CI runs.
• npm run test:tools — hits the real mailbox, creating then sweeping [MCP TEST] artifacts. MCP_TEST_SKIP='^g\.' leaves out the auto-reply test, whose reply a real sender could receive mid-run.
• npm run test:remote — hits the deployed Worker; needs an interactive device-code sign-in or reports the authenticated tests as SKIP. MCP_REMOTE_URL retargets it at another deployment.
• npm run seed:kv — lifts the refresh token from the local token cache (~/.config/outlook-mcp/token-cache.json) into KV. Re-run only after npm run login, never routinely.
• ./run-school.sh [server|login|verify|doctor] — the second instance (work/school M365 account, its own client id, authority, cache and scopes). Its exports beat .env; the personal instance is untouched.

Standing rules

• src/core/registry.ts is the single source of the tool/prompt/resource surface; both transports build their server from it, so a tool not registered there (with its MCP annotations) exists on neither.
• No secret, token or live mailbox content ever enters this repo. ASSUMPTIONS.md, RUN-REPORT.md and cleanup-progress.md are gitignored build journals quoting real mail — never commit them, and never lift their content into a tracked file.
• send_draft is the only send path and it takes an existing draft id. Never add a compose-and-send tool, never call /me/sendMail, and never let an autonomous path send, delete or reply. The single exception is the self-alert route (core/self-alert.ts, off unless SELF_ALERT_SECRET is set): it may call /me/sendMail autonomously, but only to ALLOWED_MS_UPN, only behind that shared secret, under its daily cap, and with no caller-supplied recipient, cc, bcc or reply-to. It may be narrowed, never widened.
• Mailbox deletes stay soft. Only two tools may destroy for good, and both say so loudly: manage_task delete, and manage_scheduled_send cancel, which Exchange discards outright. A removed event may skip Deleted Items, but stays recoverable in Outlook on the web.
• Mail is untrusted input: the auto-filing rails (PROTECTED_SUBJECT_PATTERNS, confidence threshold, daily call cap) may be extended, never weakened, and both LLM features ship disabled.