Graph Mail MCP

A local stdio Model Context Protocol server for Microsoft 365 mail. It provides controlled Outlook/Exchange Online search, read, thread, attachment, and draft workflows through Microsoft Graph.

It never sends, deletes, moves, copies, archives, or marks messages as read. Raw Graph URLs, raw OData, and unrestricted Graph requests are not exposed.

Requirements

• Windows with Microsoft Edge
• Node.js 22+
• A Microsoft 365 work or school account with Exchange Online
• Delegated Mail.ReadWrite permission

Personal Microsoft accounts are disabled by default. Shared mailboxes additionally require Exchange delegation and Mail.ReadWrite.Shared.

Install

git clone https://github.com/hanhandly/graph-mail-mcp.git
Set-Location graph-mail-mcp
npm ci
npm run build
Copy-Item config.example.json config.local.json

config.local.json is ignored by Git. Review it before authentication, especially tenant, allowedMailboxScopes, and shared-mailbox settings.

Authenticate

node dist\cli.js -c config.local.json doctor
node dist\cli.js -c config.local.json auth login --account-hint user@contoso.com
node dist\cli.js -c config.local.json auth status

Login opens an isolated Microsoft Edge profile and uses Graph Explorer for delegated authentication. Playwright clicks Sign in, selects the hinted account, and checks whether the required mail permission is already consented. If it is, authentication continues automatically; otherwise the CLI tells the user which permission must be granted. Playwright never clicks Consent. MFA and consent confirmation remain user-controlled. auth status returns metadata, unexpected-scope warnings, and a next action, but never displays the token.

Graph Explorer can return permissions previously granted to its shared application. The default unexpectedTokenScopePolicy: "warn" keeps the local workflow usable while reporting scopes beyond the configured mail and sign-in allowlist. Set it to "reject" for strict environments; a dedicated app registration is the recommended way to obtain a genuinely least-privilege token.

Configure an MCP client

Use absolute paths in the client's MCP configuration:

{
  "mcpServers": {
    "graph-mail": {
      "command": "node",
      "args": [
        "C:\\Tools\\graph-mail-mcp\\dist\\cli.js",
        "-c",
        "C:\\Tools\\graph-mail-mcp\\config.local.json",
        "serve"
      ],
      "cwd": "C:\\Tools\\graph-mail-mcp"
    }
  }
}

Some clients use a different outer key, but the command, args, and cwd values are the same. Keep -c <config-path> before serve. The server uses stdio and does not open a network port.

Restart the MCP client, then call:

1. mail_auth_status
2. mail_list_folders
3. mail_search_messages

Tools

Area	Tools
Authentication and folders	mail_auth_status, mail_list_folders
Search and read	mail_search_messages, mail_get_message, mail_get_thread
Attachments	mail_list_attachments, mail_get_attachment
Managed drafts	mail_create_draft, mail_update_draft

Draft updates are limited to drafts created and registered by this MCP. There is no send tool.

bodyMode is enforced consistently: none omits body content and previews, preview returns bodyPreview, and text or html returns the message body. Responses are bounded by maxMessageBodyCharacters per message and maxTotalBodyCharacters overall; truncated messages carry bodyTruncated: true and the response provenance records the limit.

Security

The Graph transport uses a deny-by-default policy firewall and typed request compiler. Tokens are stored outside the repository and protected with Windows DPAPI by default. Logs and tool responses must not expose access tokens, cookies, or authorization headers.

The server accepts delegated tokens only, always rejects Mail.Send, reports unexpected scopes by default, and can reject them in strict mode. Its request firewall limits runtime operations, but deployments requiring a strictly least-privilege bearer token should use a dedicated app registration or constrained authentication provider.

See Security, Tool reference, Configuration example, and Architecture.