@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.3.0 · 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.

{
  "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/<account>.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": ["<path-to-repo>/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)

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 page client-side: Graph applies $top first, so the result is the sorted view of whichever page Graph returned, not a globally ordered scan of the mailbox. Unfiltered list_emails still sorts server-side.
• Recipients are validated. to/cc/bcc entries must be email addresses (trimmed, max 254 chars, max 500 recipients per field); invalid entries are rejected before any Graph call.
• Scheduled out-of-office windows require ISO 8601 date-times; explicit offsets are converted to UTC (zone-less values are treated as UTC) and the start must be earlier than the end.

Security notes

• Token files are written by the host with mode 0600; this server reads them via the cohort-shared library, which fails closed on malformed files.
• MICROSOFT_DISABLE_REFRESH=1 is the default on cloud surfaces so the desktop session remains the sole refresh-token authority and avoids racing for single-use refresh tokens.
• Successful tool responses drop the OSS-only ok:true wrapper to match the bundled successResult shape; manual validation/business errors return isError:true with a { ok:false, error, action_required, next_step } payload so the host's recovery layer can act on them.
• Per-tool Graph calls run under a composed caller + cohort timeout signal via .options({signal}) plus a Promise.race wrapper for defence-in-depth.
• download_attachment writes only inside MCP_WORKSPACE_PATH (or the OS temp directory when unset), rejects anything but a plain filename, and caps downloads at 25 MB. Attachment bytes are streamed from the $value endpoint with a hard byte cap (never fully materialized past the limit), metadata is streamed with a hard 1 MB cap for the same reason, and the workspace root is canonicalised (symlinks resolved) before anything is written. Each download is saved into a fresh, private staging directory created atomically (fs.mkdtemp, mode 0700) directly under the canonical workspace root, carrying over only the attachment file name; the reported savedTo points inside that staging directory. Because the connector invents the directory name, there is no validated user-visible pathname to pre-plant, rename, or symlink-swap between validation and the write syscall, so the parent-directory check-then-use race is removed by construction — on every platform, with no descriptor-relative APIs. The file itself is created with an exclusive open (O_CREAT|O_EXCL, mode 0600), so overwrite is impossible and a pre-existing same-named file or symlink is never touched; a failed write removes its whole staging directory, leaving no residue. Attacker-controlled attachment fields (name, type, content type) are wrapped in untrusted-content envelopes wherever they surface as text, including error paths. savedTo necessarily reports the real file path (the host needs it to open the file), but the human-facing message names only the connector-invented staging directory, so the attacker-authored file name is never echoed as trusted prose.
• Error guidance for non-authentication failures never recommends re-authentication: Graph 403 permission denials are answered with connector-local guidance explaining that re-authenticating the same account will not help, and upstream Graph error text is enveloped as untrusted content before it reaches the model.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. Free for non-competing use; relicenses to MIT on the converter date in LICENSE.