mcp-outlook

A safe-by-default Model Context Protocol server for Microsoft Outlook mail, over Microsoft Graph. It lets an agent read and operate a mailbox — list folders and messages, full-text search, read bodies and attachment metadata, list contacts, and (in higher modes) create drafts, send / reply / forward, mark read, move messages, and delete. It also manages OneDrive files — browse, search, download, upload, create folders, move/rename, and delete.

Browser sign-in: on first run it opens your browser to the Microsoft sign-in page, then caches the token and refreshes it silently — the server never sees your password.

Part of the dockndevai MCP server suite — one governance model across all of them.

What it gives an agent

The server starts read-only (see Safe by default); higher-capability tools are only registered when you raise the mode.

Install

npx -y @dockndevai/mcp-outlook

You need an Entra (Azure AD) app registration. For the default browser sign-in, register a public client and add the redirect URI http://localhost (platform: Mobile and desktop applications), then use its Application (client) ID as OUTLOOK_CLIENT_ID. Grant delegated Mail.Read (and Mail.Send / Mail.ReadWrite if you want to send or organize). No client secret is needed for interactive use.

Prefer automation? Use app-only auth instead: set OUTLOOK_CLIENT_SECRET + OUTLOOK_TENANT_ID + OUTLOOK_USER (see Authentication).

Configure

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-outlook"],
      "env": {
        "OUTLOOK_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "OUTLOOK_TENANT_ID": "common",
        "OUTLOOK_MODE": "read-only"
      }
    }
  }
}

On first use the server opens your browser to sign in and caches the token at ~/.mcp-outlook/token.json (0600); later runs refresh silently.

See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf snippets, and .env.example for every supported variable.

Authentication

Auth mode is chosen automatically (override with OUTLOOK_AUTH):

• interactive (default) — only OUTLOOK_CLIENT_ID set. Authorization-code + PKCE with a loopback redirect: the browser opens, you approve once, and the access + refresh token are cached on disk. Operates on the signed-in user's mailbox (/me). The server never handles your password.
• client-credentials (app-only) — OUTLOOK_CLIENT_SECRET present. The server fetches an app token itself; requires OUTLOOK_TENANT_ID and OUTLOOK_USER (the mailbox to act on, since an app token has no signed-in user). Grant the app application Mail permissions with admin consent.
• token — OUTLOOK_TOKEN set to a pre-obtained Graph bearer token. You manage its lifetime.

Safe by default

The access model is enforced by src/security.ts — defence in depth on top of the Graph token's own scopes/roles:

• OUTLOOK_MODE — read-only (default) → read-write → admin. A tool is registered only if the mode allows its capability. Read-only exposes the 7 read tools; drafts/moves need read-write; deletes need admin.
• OUTLOOK_ALLOW_SEND — sending mail (send / reply / forward) can't be undone, so on top of read-write it also requires this flag. Drafting is always allowed in read-write; nothing leaves the mailbox until sent.
• OUTLOOK_ALLOW_DELETE — deletes require this flag on top of admin mode.
• OUTLOOK_FOLDER_ALLOWLIST / OUTLOOK_PROTECTED_FOLDERS — confine which folders can be written to / moved into; mark folders (e.g. sentitems, archive) that may be read but never modified.
• Interactive confirmation — when the client supports MCP elicitation, sending mail and deleting a message pause and ask the human to approve before running; clients that can't elicit fall back to the OUTLOOK_ALLOW_SEND / OUTLOOK_ALLOW_DELETE gates.
• OUTLOOK_DRY_RUN — validate and log writes without executing them.
• OUTLOOK_AUDIT_LOG — a JSON audit line per guarded operation, on stderr (default on).
• Attachment bytes are never returned — list_attachments returns metadata only.

See SECURITY.md.

Developing

npm install
npm run build
# introspect the tool list without signing in (uses a fake token, no network):
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | OUTLOOK_TOKEN=x node dist/index.js
npm test

Licence

MIT