Outlook Mail

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 claude_desktop_config.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 OUTLOOK_TENANT=organizations -e OUTLOOK_CLIENT_ID=your-client-id -- npx -y @pepebits/outlook-mcp.

🔐 Authentication

npx -y @pepebits/outlook-mcp auth      # device code sign-in; prints a URL and a code
npx -y @pepebits/outlook-mcp whoami    # silent token + GET /me
npx -y @pepebits/outlook-mcp logout    # removes accounts and deletes the token cache (keychain entry and file)

You can also sign in without a terminal. Just ask your assistant to "log in to Outlook":

• 🔑 login returns a URL and a one-time code. Open the URL, enter the code and accept; sign-in finishes in the background.
• ✅ auth_status tells you whether you are signed in, still waiting, or signed out.
• 🚪 logout removes the cached account and the token cache (keychain entry and file).

Use login with force: true to sign in again, for example after adding a permission in Azure. If the session is missing or expired, tools return "Not signed in or session expired. Call the login tool ...".

🗝️ Token storage

The refresh token is the most sensitive thing this server holds, so by default (OUTLOOK_TOKEN_STORE=auto) it goes into the operating system keychain instead of a plain file. No native npm dependencies are used; the server calls the OS tools directly:

• Migration: if a cache file exists and the keychain is still empty, it is imported into the keychain and the file is deleted.
• Fallback: in auto mode, if the keychain cannot be used at runtime the server falls back to the file and logs a warning. OUTLOOK_TOKEN_STORE=keychain never falls back and fails instead; file never touches the keychain.
• Secrets stay out of process listings: on Linux secret-tool reads the secret from stdin. security add-generic-password only accepts the password as a command-line argument (visible in ps to other local processes), so on macOS the commands are fed to security -i over stdin instead. That interface truncates lines at about 4 KB, so the cache is stored base64 encoded across a few small keychain items (<account>#0, #1, ...).
• logout (tool and CLI) removes the keychain entry as well as the file.
• On macOS the first access from a different binary may show a Keychain prompt; click Always Allow.

🛠️ Use your own Azure app (optional)

By default outlook-mcp uses the shared outlook-mcp Azure app, which works with personal Microsoft accounts only. Register your own app if you need work or school accounts or simply prefer to use your own. Then set OUTLOOK_CLIENT_ID (and OUTLOOK_TENANT, see below).

Step by step

1. Open portal.azure.com and go to Microsoft Entra ID -> App registrations -> New registration.

2. Give it a name (for example outlook-mcp).

3. Under Supported account types choose:

   • Personal Microsoft accounts only (Outlook.com, Hotmail, Live), or
   • Accounts in any organizational directory and personal Microsoft accounts (both).
   • For work/school only, pick an organizational option.

4. Leave Redirect URI empty and click Register.

5. In the left menu go to Manage -> Authentication -> Settings tab, set Allow public client flows to Yes and save.

6. Go to Manage -> API permissions. User.Read is already granted by default. Click Add a permission -> Microsoft Graph -> Delegated permissions and add:

   • 📬 Expand the Mail group and tick Mail.ReadWrite and Mail.Send.
   • ⚙️ Expand the MailboxSettings group and tick MailboxSettings.ReadWrite (needed for inbox rules and block_sender).
   • 🔑 Expand the OpenId permissions group and tick offline_access.

   Then click Add permissions. No admin consent is needed for personal accounts.

💡 If you upgrade from 0.1.0, add MailboxSettings.ReadWrite in Azure and run login with force: true (or npx -y @pepebits/outlook-mcp auth) again.

💡 The Azure portal may be shown in your language, so labels can differ slightly (e.g. Administrar -> Autenticación -> Configuración, Permisos de OpenId).

7. From the Overview page copy the Application (client) ID. This is your OUTLOOK_CLIENT_ID.

🏢 Work or school accounts: set OUTLOOK_CLIENT_ID to your app and OUTLOOK_TENANT=organizations (or your tenant GUID). Your organization may require admin consent for the mail permissions.

🧰 Tools reference

Bulk operations: the tools marked "Accepts id or ids" take exactly one of the two. With ids they process up to 50 messages (a few at a time), never stop at the first error and return { results: [{ id, ok, ... | error }], succeeded, failed }. With id the response is unchanged.

Well-known folder names accepted anywhere a folder id is expected: inbox, drafts, sentitems, deleteditems, junkemail, archive.

📬 Daily digest

Ask "What's waiting in my inbox today?" and the assistant calls mail_digest: it scans the unread mail of the last 24 hours (adjust with since, unreadOnly, maxMessages) and returns counts (total, unread, flagged, high importance, with attachments), the high-importance and flagged messages, and the messages grouped by sender with their latest subject and a few message ids. For the top 20 senders it checks the List-Unsubscribe header, so newsletters are marked with isNewsletter and can be handed straight to unsubscribe.

🧹 Cleaning up your inbox

Ask Claude something like "Find the newsletters cluttering my inbox, unsubscribe from the ones I don't read and block the rest". Behind the scenes:

1. find_newsletters scans the inbox and lists senders with a List-Unsubscribe header, most frequent first, each with a sampleMessageId and an unsubscribe method (one-click, mailto or link).
2. unsubscribe with ids set to the chosen sample message ids leaves those lists. Senders that only offer a link come back with the URL to open in a browser.
3. block_sender with addresses or domains creates an inbox rule that sends their future mail to Deleted Items. Use delete_message with ids to clear what is already in the inbox, and list_rules / delete_rule to review or undo a block.

Inbox rules need the MailboxSettings.ReadWrite permission (see the Azure steps above). Do not unsubscribe from spam or phishing: it confirms your address is active. Block those senders instead.

🔎 Bulk clean-up by search

Ask "Archive everything from newsletters@shop.com received before 2025". bulk_action always starts as a dry run: it changes nothing and returns the match count plus a sample of 10 messages.

{ "from": "newsletters@shop.com", "until": "2025-01-01", "action": "archive" }

Confirm the count with the assistant, then it calls the tool again with dryRun: false to apply the action:

{ "from": "newsletters@shop.com", "until": "2025-01-01", "action": "archive", "dryRun": false }

Use either query (KQL, e.g. from:shop.com hasattachments:true) or the filter fields, not both. At most max messages are processed (default 100, hard cap 500) and the response says if the result was truncated; run it again for the rest. delete moves to Deleted Items (recoverable), archive moves to the Archive folder, and move needs destinationFolderId. Failures never stop the run: the response lists each id with ok or error.

👁️ Read-only mode

Set OUTLOOK_READ_ONLY=true to register only the non-mutating tools. The mutating tools do not exist for the client, so they cannot be called at all. Combine it with a token cache created using only User.Read Mail.Read (set OUTLOOK_SCOPES accordingly and re-run npx -y @pepebits/outlook-mcp auth) for defense in depth.

🛡️ Security

• 🔑 The token cache is stored in the OS keychain when available (macOS Keychain, Linux Secret Service; see Token storage), otherwise in a local file with mode 0600 in a 0700 directory, written atomically.
• 🙅 No client secret exists: this is a public client using device code flow.
• 🤐 Tokens and message bodies are never logged; MSAL PII logging is disabled.
• 📥 Attachment downloads are confined to OUTLOOK_DOWNLOAD_DIR; path traversal is rejected.
• ⚠️ delete_message with permanent: true is irreversible, and send_mail, reply_message and forward_message send immediately. Prefer read-only mode or create_draft when in doubt.
• 🧠 Email content is untrusted input: a malicious message may try to instruct the model (prompt injection). To help the model tell data from instructions, results from get_message, list_messages, search_messages, list_attachments and find_newsletters group sender-controlled text (subjects, senders, previews, attachment names) under an untrusted key and carry a note saying so. The get_message body is enclosed in <untrusted_email_content> markers, and any marker found inside the content is neutralized so it cannot close the wrapper early.
• 🤝 The server also sends MCP instructions telling clients that email content is untrusted and that sending, deleting, unsubscribing and rule changes should be confirmed with the user. These are mitigations, not guarantees: keep a human in the loop for those actions or use read-only mode.

🩺 Troubleshooting

🧑‍💻 Development

git clone https://github.com/Pepebits/outlook-mcp.git
cd outlook-mcp
npm install
cp .env.example .env        # optional
npm run build
npm test

Run it from source in your MCP client:

claude mcp add outlook --scope user -- node /absolute/path/outlook-mcp/dist/index.js

Use npm run inspect to try the tools in the MCP Inspector.

🚢 Releasing (maintainers)

1. Move the [Unreleased] notes in CHANGELOG.md under the new version, bump the version in package.json and server.json (top level and package), commit and push.
2. Tag it: git tag -a vX.Y.Z -m "Short summary" && git push origin vX.Y.Z. The Release workflow runs the tests, stages the version on npm (Trusted Publishing, with provenance) and creates the GitHub release.
3. Approve the staged version on npmjs.com (or npm stage approve <stage-id>), which needs your 2FA.
4. The workflow waits for the approval, lists the version in the MCP Registry and announces the release on Telegram. If you approve more than ~6 hours later, the wait times out: run the Release workflow by hand (Actions → Release → Run workflow) with the tag to announce it.

🗺️ Roadmap

This server is about mail only; calendar and other Microsoft 365 data are out of scope.

There is nothing planned right now. Ideas are welcome: open an issue.

🤝 Contributing

Issues and pull requests are welcome.

npm install
npm run typecheck
npm test
npm run build

Please keep code, comments and docs in English, add tests for new behavior, and never log secrets or message content.

📄 License

MIT