Outlook Mail MCP server

A Model Context Protocol server that lets Claude, Codex and any other MCP client read, search, send and organize your Outlook / Microsoft 365 / Outlook.com mail through the Microsoft Graph API.

🔭 Overview

outlook-mcp runs locally over stdio. It signs in with the OAuth device code flow (no client secret, no redirect URI), stores the refresh token in your OS keychain (or a local file only you can read), and talks to Microsoft Graph with plain fetch.

✨ Features

• 📂 Browse folders, list and search messages (KQL), read bodies as sanitized plain text
• 📎 List and download attachments safely into a configured directory
• ✉️ Send mail, create drafts, reply, reply-all and forward (local attachments up to 150 MB; files of 3 MB or more are uploaded in chunks)
• 🗂️ Move, mark read/unread, flag and delete messages, one at a time or in bulk (ids)
• 📰 Find newsletters, unsubscribe from them and block unwanted senders with inbox rules
• 🔒 Read-only mode that removes every mutating tool
• 🔁 Automatic retry with Retry-After / exponential backoff for throttling (429/503/504)
• 🧾 Logs only to stderr; never logs tokens or message bodies

📋 Requirements

• Node.js 24 (LTS) or newer
• A Microsoft account (personal works out of the box; work or school needs your own Azure app)

🚀 Quick start

No terminal sign-in and no Azure setup needed. You only need Node.js 24+.

Claude Code

claude mcp add outlook --scope user -- npx -y @pepebits/outlook-mcp

Claude Desktop

Add to claudedesktopconfig.json and restart Claude Desktop:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["-y", "@pepebits/outlook-mcp"]
    }
  }
}

Codex (OpenAI)

codex mcp add outlook -- npx -y @pepebits/outlook-mcp

Or add it to ~/.codex/config.toml (shared by the Codex CLI and IDE extension):

[mcp_servers.outlook]
command = "npx"
args = ["-y", "@pepebits/outlook-mcp"]
# env = { OUTLOOK_READ_ONLY = "true" }

Run /mcp inside Codex to check that it is connected.

Other MCP clients

Any client that can launch a stdio MCP server works: run npx -y @pepebits/outlook-mcp as the server command.

Sign in

Ask your assistant to "log in to Outlook". The login tool returns a URL and a one-time code: open the URL, enter the code and accept. Prefer a terminal? Run npx -y @pepebits/outlook-mcp auth instead.

By default the server uses the shared outlook-mcp Azure app, which supports personal Microsoft accounts (outlook.com, hotmail, live). The consent screen may show an unverified publisher warning. No data passes through any server of ours: the server talks to Microsoft Graph directly from your machine and your tokens stay in the local token cache. For work or school accounts, or to use your own app, see Use your own Azure app.

⚙️ Configuration (.env)

The .env file is optional. Variables are read from .env in the current directory and in the package directory, and real environment variables override it. You can also pass them through your MCP client's env block, e.g. claude mcp add outlook --scope user -e OUTLOOKTENANT=organizations -e OUTLOOKCLIENT_ID=your-client-id -- npx -y @pepebits/outlook-mcp.

Shortened. The full README is on GitHub.