Microsoft 365 Mail

@mindstone/mcp-server-microsoft-mail

Microsoft 365 Outlook Mail MCP server — list, search, read, send, reply, forward, draft, move, and delete email, download attachments, read threads, triage (read/flag), and manage out-of-office replies via the Microsoft Graph API.

*Cohort-style Microsoft 365 mail MCP. Host owns the OAuth flow, this server reads per-account tokens off disk, and each tool fails closed with a structured auth_required envelope so the host can drive reauth.*

Status

• Version: 0.4.1 · npm
• Auth: OAuth (host-orchestrated) (MS_CLIENT_ID)
• Tools: 22 (messages, folders, drafts, attachments, threads, settings)
• Surface: cloud-api
• Machine-readable: STATUS.json
• Shared library: @mindstone/mcp-server-microsoft-shared

Why this exists

When we ported this in May 2026, Microsoft's own Graph MCP lineup did not yet ship a stand-alone Outlook Mail server, and the community options at the time each ran their own browser-callback server during OAuth — which our host application already does, with credentials it has already negotiated for the rest of the cohort. We pulled the bundled connector out of MindstoneRebel as a 1:1 port so the same five-connector Microsoft 365 cohort (mail, calendar, files, teams, SharePoint) shares a single OAuth surface, a single shared-library package for token persistence, request timeouts, and the structured auth_required envelope the host already knows how to recover from. This connector owns the cohort's authentication tool (authenticate_microsoft_account); the other four connectors reuse the credentials it negotiates.

Example interaction

"List my five most recent unread emails from Alice and reply to the latest one with 'thanks, will read tonight'."

Tools the host calls:

1. search_emails — from:alice@example.com isRead:false, top 5.
2. reply_to_email — sends a reply on the top-result message ID with the supplied body.

Response (trimmed):

{

"matches": [ { "id": "AAMkAD...", "subject": "Q3 planning", "from": "alice@example.com", "receivedDateTime": "2026-05-19T09:14:11Z" } ], "reply": { "id": "AAMkAD...", "isDraft": false } }

Requirements

• Node.js 20+
• npm
• A host application that performs the Microsoft OAuth flow and writes per-account token files into ${MS_CONFIG_DIR}/credentials/${sanitised-email}.token.json and an ${MS_CONFIG_DIR}/accounts.json index. This server reads those files; it does not initiate OAuth itself.

One-click install

After clicking the button, your host will prompt you to fill: MS_CLIENT_ID, MS_CONFIG_DIR, MS_MCP_PACKAGE_ID, MICROSOFT_REQUEST_TIMEOUT_MS.

Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Microsoft 365 Mail)

{

"mcpServers": { "Microsoft 365 Mail": { "command": "npx", "args": [ "-y", "@mindstone/mcp-server-microsoft-mail" ], "env": { "MS_CLIENT_ID": "", "MS_CONFIG_DIR": "", "MS_MCP_PACKAGE_ID": "Microsoft365Mail", "MICROSOFT_REQUEST_TIMEOUT_MS": "60000" } } } }

Quick Start

Install & build

cd <path-to-repo>/connectors/microsoft-mail

npm install npm run build

npx (once published)

npx -y @mindstone/mcp-server-microsoft-mail

Local

node dist/index.js

Configuration

This server runs alongside a host application that owns the Microsoft 365 OAuth flow. The host writes credentials to disk; this server reads them.

Required environment variables

Optional environment variables

Host configuration examples

Claude Desktop / Cursor

{

"mcpServers": { "Microsoft365Mail": { "command": "npx", "args": ["-y", "@mindstone/mcp-server-microsoft-mail"], "env": { "MS_CLIENT_ID": "your-entra-application-client-id", "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config" } } } }

Until the host has written ${MS_CONFIG_DIR}/credentials/ .token.json and ${MS_CONFIG_DIR}/accounts.json, every tool call returns the structured auth_required response (the host's MCP service recognises this shape and dispatches to its registered Microsoft 365 OAuth orchestrator).

Local development (no npm publish needed)

{

"mcpServers": { "Microsoft365Mail": { "command": "node", "args": [" /connectors/microsoft-mail/dist/index.js"], "env": { "MS_CLIENT_ID": "your-entra-application-client-id", "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config" } } } }

Tools (22)

Compose send status

In hosts that remember send status, sending an email closes its other compose copies. Reloaded cards show "Email sent" with the send time and hide Reopen because they do not have the sent contents. The copy used to send keeps its posted contents in a read-only sent view, including when confirmation follows a lost reply. After an error or block reply, a later sent status from another copy shows only the sent bar, without this copy's contents. While a send is in progress, other copies show “Sending…” with Send, Retry, Cancel and Save draft (where available) disabled. Replies to this copy’s own requests keep those controls locked until the other send ends. If the send ends without a confirmed outcome, those copies return to editing and keep any earlier uncertainty. A copy waiting for its own Send reply keeps its sending view. Sent views stay read-only, and uncertainty remains until a send is confirmed. After an error or missing confirmation, check whether the email was sent before using Retry; the notice stays visible while editing and returns on Reopen. Collapsing the card does not resolve that uncertainty. Policy-block explanations stay visible while editing with Send disabled. Cancel says "Nothing sent" only when no send may have gone through, including a not-dispatched failure before the request left the device.

When sending is blocked by your settings, your organization or security policy, the card hides Retry and keeps Cancel. If the server is stopped, Retry remains available.

Send requests declare _meta: { 'mcp-app/cardOutcome': 'sent' } to supporting hosts. Draft saves do not declare a send outcome; Cancel after a draft-save timeout says "Nothing sent" unless an earlier send remains uncertain.

Graph permissions

Mail tools run on the Mail.ReadWrite + Mail.Send delegated grants. The automatic-replies tools additionally need MailboxSettings.Read / MailboxSettings.ReadWrite; in many organizations an administrator must approve that permission, and the tools return a guidance envelope (rather than a raw Graph 403) when the connected account lacks it.

Ordering and validation notes

• Filtered listing is page-local. Microsoft Graph rejects $filter combined with $orderby, so when list_emails is called with a filter (and always for get_conversation) the connector sorts only the returned pag