MCP Server for Multiple Outlook Accounts

A local, single-connector Model Context Protocol server that lets an AI assistant operate several Outlook / Microsoft 365 mailboxes at once — searching, reading, drafting, sending, and organising mail — through one safety-annotated tool surface, with OAuth tokens that never leave your machine.

This is the Outlook / Microsoft Graph provider variant of a provider-neutral specification.

• 📄 doc/business-specification.md — provider-neutral business + functional spec (the contract).

• 🔌 doc/provider-mapping.md — how neutral requirements bind to Microsoft Graph.

• 🏗️ doc/architecture.md — how this variant is designed and built.

• ✅ doc/traceability-matrix.md — every requirement → module → test.

Project status: phase 1 (auth core + list_accounts)

Built with TypeScript 6.0.3; build, typecheck, tests (29), and format all green. What exists today:

• ✅ Architecture design + requirements traceability matrix (doc/).

• ✅ Neutral domain types + subsystem contracts; tested config loader (src/domain/, src/config.ts).

• ✅ Auth core: Entra credential-source discovery, MSAL public-client (consent + silent refresh), secure token store (0600/0700, atomic + cross-process-locked), account-selection registry.

• ✅ Account-management CLI: outlook-mcp-auth connect | list | remove.

• ✅ C1 list_accounts MCP tool (with behavioural annotations), served over stdio.

Not yet implemented: capabilities C2–C8 (search, read, draft, send, labels, organise) and the Microsoft Graph client (timeout/retry/error-mapping). These are designed in doc/architecture.md §13 (build phases 2–4) and tracked as Planned in the traceability matrix.

Tests mock Microsoft Graph and MSAL. Live §13 acceptance — real browser consent and Graph calls — requires an Entra app registration + Outlook mailboxes and is run locally by the operator.

Related MCP server: m365-mcp-server

Planned capabilities (spec §5)

Plus an out-of-band account-management CLI (outlook-mcp-auth connect | list | remove).

Development

Requires Node.js ≥ 18 (developed on Node 22).

npm install
npm run typecheck      # tsc --noEmit
npm run build          # compile to dist/
npm test               # vitest (Graph/MSAL mocked)
npm run format:check   # prettier

Configuration

All operational knobs are environment variables (see .env.example):

Connecting a mailbox

1. Register a public-client app in Entra ID with the redirect URI http://localhost and the delegated scopes Mail.ReadWrite, Mail.Send, User.Read, offline_access.

2. Drop a credentials*.json into the data dir (or point OUTLOOK_OAUTH_CREDENTIALS at it):

   { "clientId": "<application-client-id>", "tenant": "common" }

   Multiple credentials*.json files are auto-discovered, so accounts under different app registrations each refresh with the client that authorised them.

3. Connect, list, and remove mailboxes:

   outlook-mcp-auth connect            # opens the browser for consent
   outlook-mcp-auth connect --source acme   # pick a specific app registration
   outlook-mcp-auth list
   outlook-mcp-auth remove user@example.com

Security posture

OAuth tokens are stored only on the local machine (file mode 600 in a 700 data dir). Reading local files by path for attachments is disabled by default and only allowed from an explicit allow-list. The server never logs tokens, credentials, or message content. See doc/architecture.md §9.

License

MIT — see LICENSE.