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 only and never displays the 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

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

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.

Graph Explorer may return permissions previously consented to its shared application. The server rejects Mail.Send and restricts runtime requests, but deployments requiring a strictly least-privilege token should use a dedicated app registration or constrained authentication provider.

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