io.github.dockndevai/mcp-outlook

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 — and the calendar — list calendars and events, check free/busy, and (gated) create, update, respond to, cancel and delete events.

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.

Access is ultimately governed by your Microsoft account's granted scopes. Calendar tools need the Calendars.ReadWrite delegated scope (included in the defaults). If your token wasn't consented for it, Graph returns 403 — the suite's modes/flags are defence in depth on top of that Microsoft-level control. Downscope with OUTLOOK_SCOPES (e.g. drop Calendars.ReadWrite, or use Calendars.Read for read-only).

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