mail-brief-mcp

A small, least-privilege MCP server for email. It helps your AI assistant summarize what arrived and draft replies for review. Optional cleanup tools, off by default, move selected messages to Junk and unsubscribe from supported mailing lists at your request.

Works with any MCP client that runs local servers (Claude Desktop, Codex CLI, Cursor, VS Code, …) and IMAP providers offering app passwords or OAuth (Yahoo by default; Outlook.com setup below).

Why so small

Every tool an agent has is something a malicious email can try to talk it into using. By default the only change the server can make is saving reply drafts. The cleanup tools (ENABLE_CLEANUP_TOOLS=true) add Junk moves and one-click unsubscribe:

Drafts remain available for review before sending. If you turn on the cleanup tools: Junk moves change mailbox location immediately, and one-click unsubscribe contacts an external sender and can't be undone. Keep your client's approval prompt on for move_to_junk and unsubscribe_email; the confirmed flag is filled in by the AI, so your approval is the real check.

Related MCP server: outlook-mcp-limited

Architecture

Your MCP client starts the server on your computer and talks to it over a private pipe. Nothing listens on a network port; outbound connections go to your mail provider, Microsoft identity endpoints for Outlook OAuth, and public HTTPS unsubscribe endpoints when you request an unsubscribe.

flowchart LR
    subgraph Mac["Your computer"]
        Host["Claude Desktop / Codex / Cursor<br/>(MCP host + client)"]
        Server["node src/server.js<br/>mail-brief-mcp · Node.js"]
        Keychain[("OS keychain / password store<br/>app password or refresh token")]
        Env[".env or .env.outlook<br/>address + auth settings"]
    end
    OAuth["Outlook token helper"]
    Identity["Microsoft identity · HTTPS 443"]
    Server -->|"MAIL_OAUTH_TOKEN_COMMAND"| OAuth
    OAuth <-->|"refresh token"| Keychain
    OAuth <-->|"OAuth refresh"| Identity
    Mail[("IMAP_HOST<br/>imap.mail.yahoo.com, imap.mail.me.com, …")]

    Host <-->|"MCP · JSON-RPC 2.0 over stdio<br/>no network port"| Server
    Server -->|"child process<br/>MAIL_PASSWORD_COMMAND"| Keychain
    Server -->|"read at startup"| Env
    Server <-->|"IMAP over TLS 1.2+<br/>TCP 993"| Mail

No HTTP server and no credential files written to disk. Outlook uses OAuth over HTTPS and stores its refresh token in Keychain.

For components, request flows, trust boundaries, and design decisions, see ARCHITECTURE.md and Outlook design.

Tools

Setup

1. Install

git clone https://github.com/praneethpalla/mail-brief-mcp.git
cd mail-brief-mcp
npm install

For Outlook.com, follow Outlook.com setup instead of steps 2–3.

2. Create an app password and put it in a password store

Create an app password with your provider (see Providers; Yahoo: account security → Generate app password). Then store it; the server never reads a password from a file.

macOS Keychain:

# You'll be prompted for the password (hidden; it never lands in your shell history).
# -T "" trusts no app, so macOS asks you to Allow or Deny every read.
security add-generic-password -a you@yahoo.com -s mail-brief-mcp -T "" -w

Windows Credential Manager:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\windows-credential.ps1 -Set -User you@example.com

Others: any command that prints the password works, e.g. op read "op://Private/Mail/password" (1Password), secret-tool lookup service mail-brief-mcp (Linux keyrings), pass show mail-brief-mcp.

3. Configure

cp .env.example .env

MAIL_ADDRESS=you@yahoo.com
MAIL_PASSWORD_COMMAND=security find-generic-password -a you@yahoo.com -s mail-brief-mcp -w
# IMAP_HOST=imap.mail.yahoo.com   (change for other providers)

4. Add it to your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mail-brief": {
      "command": "node",
      "args": ["/full/path/to/mail-brief-mcp/src/server.js"]
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.mail-brief]
command = "node"
args = ["/full/path/to/mail-brief-mcp/src/server.js"]

Restart the client and ask something like "Summarize my unread emails from today" or "Draft a reply to Alice saying Friday works." With the strict Keychain setting, macOS asks you to Allow access when the server first logs in.

Providers

The server signs in with an app password or OAuth over IMAP. Providers differ, and their policies change, so check yours:

Yahoo has been live-tested. Outlook.com OAuth sign-in, token refresh, listing, and reading without changing read status have been live-tested; Outlook draft creation and updates still need live validation. Other providers remain untested.

Dates (since, before) are calendar days in your local time (2026-10-01 means October 1 where you are) and use the date the email was sent.

Outlook.com setup

1. In Outlook.com settings, enable IMAP under Settings → Mail → Forwarding and IMAP.

2. Register an application in Microsoft Entra. Choose an account type that includes personal Microsoft accounts. Copy its Application (client) ID. Under Authentication → Advanced settings, enable Allow public client flows. No client secret is needed.

3. For personal Outlook.com accounts, the helper requests https://outlook.office.com/IMAP.AccessAsUser.All and offline_access during sign-in using dynamic consent. You do not need to find or add the permission in the portal first. It does not request SMTP or Microsoft Graph permissions. See Microsoft’s IMAP OAuth scopes and dynamic delegated consent.

4. Create a separate .env.outlook so your Yahoo configuration stays available:

MAIL_ADDRESS=you@outlook.com
MAIL_AUTH=oauth2
OUTLOOK_CLIENT_ID=your-application-client-id
MAIL_OAUTH_TOKEN_COMMAND=node "/full/path/to/mail-brief-mcp/scripts/outlook-auth.js" token
# OUTLOOK_TENANT=consumers
READ_ONLY=true

5. On macOS, run the one-time sign-in from the project directory:

ENV_FILE=.env.outlook npm run outlook:login

Open the Microsoft URL printed by the helper, enter the code, and sign in with the account matching MAIL_ADDRESS. Approve consent and Keychain prompts. The refresh token is stored under a Keychain service specific to this app ID and email address, readable by the macOS security tool that created it. Access tokens remain in memory; rotated refresh tokens replace the Keychain entry.

6. Add a second MCP server entry using the same node command and src/server.js path as Yahoo, with ENV_FILE set to .env.outlook in its environment. For example, in Codex:

[mcp_servers.outlook-brief]
command = "node"
args = ["/full/path/to/mail-brief-mcp/src/server.js"]
env = { ENV_FILE = ".env.outlook" }

Restart your client and list or read a few messages. To test drafts later, remove READ_ONLY=true, restart the client, then create a reply draft and inspect it in Outlook. This project cannot send mail. Microsoft's IMAP permission itself allows broad mailbox access, even when this server runs in read-only mode. To disconnect, revoke the app's consent in your Microsoft account and delete its mail-brief-mcp-outlook-<client-id> Keychain entry.

If login fails, check IMAP enablement, the account address, public client flows, and consent; run the sign-in command again if Microsoft has revoked the refresh token. Microsoft 365 work/school accounts can use OUTLOOK_TENANT=organizations or a tenant ID, subject to their organization's policies; they have not been live-tested.

The included helper requires macOS. On Windows or Linux, set MAIL_OAUTH_TOKEN_COMMAND to a secure helper that prints only {"access_token":"...","expires_in":3600} and handles refresh-token storage and renewal. Never put access or refresh tokens in .env.

Claude Desktop configuration for Outlook

Add this entry inside your existing mcpServers object, alongside Yahoo. Replace both paths with the location of the copy you want to run:

{
  "mcpServers": {
    "outlook-brief": {
      "command": "node",
      "args": ["/full/path/to/mail-brief-mcp/src/server.js"],
      "env": { "ENV_FILE": ".env.outlook" }
    }
  }
}

If your desktop client cannot find node, use the absolute path returned by command -v node. Configuration changes require a client restart. Each Yahoo or Outlook entry starts a separate process and connection; explicitly name the server when asking about email.

Running it manually

Run commands from the project folder:

cd /full/path/to/mail-brief-mcp
npm test
ENV_FILE=.env.outlook npm start

npm start starts a stdio MCP process. It waits for an MCP client; it does not display your inbox in the terminal. Stop a manual run with Ctrl+C. For normal use, let your MCP client launch the process using the configuration above.

Use the same project path in both the MCP server's args and .env.outlook's MAIL_OAUTH_TOKEN_COMMAND. ENV_FILE resolves relative to the project containing the script, regardless of the client working directory. Inherited environment variables take precedence over values in the file; remove conflicting MAIL_AUTH, MAIL_ADDRESS, or ENV_FILE settings from your client environment.

Copies on the same Mac with the same client ID and mailbox address share the same Keychain refresh-token entry. Copying the project to a different computer does not copy Keychain credentials; run outlook:login there. The configuration files contain personal settings, so keep .env and .env.outlook private; Git ignores them.

Outlook verification

npm test runs 46 offline tests and does not contact Microsoft. For a live check after configuring your MCP client:

Live-tested on a personal Outlook.com account: device sign-in, refresh-token storage and renewal, listing, and reading without changing read status. Live search, draft creation, and draft updates remain to be verified. Offline draft tests cover shared tool behavior but do not establish Outlook-specific draft behavior.

Outlook troubleshooting

For a fresh machine or project checkout, follow the full setup above rather than assuming the saved copy includes Microsoft credentials.

Junk and unsubscribe usage

These tools are off by default. Add ENABLE_CLEANUP_TOOLS=true (and no READ_ONLY=true) to the settings file, restart your MCP client, then ask:

• “Using outlook-brief, move email UID 123 from INBOX to Junk.”

• “Using outlook-brief, show unsubscribe options for email UID 456.”

• “Unsubscribe me from that mailing list using the one-click destination you showed.”

Use real UIDs returned by list or search; they are folder-specific. Moving to Junk changes the message's location and may assign a new UID. It does not create a block rule, train spam filtering, or unsubscribe. The server detects \Junk or common folder names; set JUNK_FOLDER only if detection fails. Native IMAP MOVE is required; there is no copy/delete fallback that might expunge unrelated messages.

Unsubscribe has two stages: inspect the headers, then submit the exact HTTPS one-click URL with confirmed=true after user authorization. The server must find a single HTTPS endpoint and a List-Unsubscribe-Post: List-Unsubscribe=One-Click header. Mailto links, ordinary web forms, missing headers, redirects, and unsupported endpoints require manual action in Outlook or a browser. It never sends unsubscribe email. A successful HTTP response means the endpoint accepted the request; the sender controls when delivery stops.

No live messages have been moved or unsubscribed during implementation. Offline coverage verifies selected-message movement, missing-UID checks, unsupported MOVE rejection, read-only enforcement, header parsing, exact URL matching, DNS protections, POST payload, and redirect refusal. For live testing, select a specific disposable message or mailing list you want changed.

Security

Where your password lives. Only in your password store. The server refuses to start if a plain-text password is set (MAIL_PASSWORD, IMAP_PASSWORD, YAHOO_APP_PASSWORD), keeps the password in memory only, and never logs it. It logs in once and reuses the connection, logging out after 5 idle minutes.

Outlook tokens. The refresh token lives in macOS Keychain; the access token is cached only in memory until one minute before expiry. Plain-text MAIL_ACCESS_TOKEN and MAIL_REFRESH_TOKEN settings are refused. The application ID is public configuration, not a secret. OAuth mode requires TLS.

App passwords are powerful. An app password usually grants full mailbox access, including sending over SMTP, even though this server never sends. Use one app password per setup, and rotate it on a short schedule and after testing. With Keychain, rotating is: generate a new app password, then run the add-generic-password command again with -U. The server re-reads it after the next failed login.

Prompt injection. Every email is text from a stranger, and it can contain instructions aimed at the AI. The server:

• returns everything the sender wrote inside <untrusted-content> blocks with random ids, which an email can't close early, plus a note telling the AI to treat it as data;

• shows only what a person would see: hidden HTML (display:none, zero-size or transparent text, off-screen elements, comments, scripts) and invisible Unicode are removed, and the HTML part is preferred over a plain-text part mail apps don't show;

• caps each email body (READ_EMAIL_MAX_CHARS, default 20,000 characters);

• labels tools with MCP hints (readOnlyHint, destructiveHint) so clients can ask before changes.

This reduces the risk; it can't eliminate it. Language models read your request and an email's text as one stream, so the real guarantees come from what the server can't do (see the table above) and from approving tool calls in your client.

Safety hooks. Automatic checks the agent can't switch off. Warnings come from the server, outside the untrusted block (⚠️ Server safety check: …):

• Reading: payment red flags (changed bank details, IBANs, account numbers, wire transfers, gift cards, crypto, urgency plus payment), a Reply-To that differs from the sender, and display-name spoofing such as "support@paypal.com" <billing@evil.example>.

• India-specific red flags: UPI IDs and "pay to this UPI ID" requests, IFSC codes, NEFT/RTGS/IMPS transfer requests, requests for an OTP, UPI PIN, or CVV, KYC/PAN/Aadhaar "verification" demands, electricity/mobile disconnection threats, courier or customs fees, and ₹/Rs/INR amounts combined with urgency. They're written to stay quiet on routine bank and fund emails ("NEFT credit received", "your SIP of ₹3,000 is due", "never share your OTP").

• Drafting: a warning when a reply would go to a Reply-To address instead of the sender, or when the draft contains payment details.

Add your own rules with SAFETY_HOOKS_MODULE: a JavaScript module exporting readEmail(ctx) and/or beforeDraft(ctx) that return { warnings: [...], block: "reason" }. If a custom hook throws, the action is blocked.

// my-hooks.mjs: never draft replies about wire transfers
export function beforeDraft(ctx) {
    return /wire transfer/i.test(ctx.body) ? { block: 'Write replies about wire transfers by hand.' } : { warnings: [] };
}

Unsubscribe requests. Links come only from standard List-Unsubscribe headers; body links are not automatically acted on. A one-click request requires the exact inspected URL and explicit user authorization. HTTPS requests use public DNS addresses pinned to the connection, reject private/local/reserved targets, validate TLS, and follow no redirects. No cookies, mailbox credentials, or Authorization headers are sent. The server does not independently verify DKIM signatures, so it does not automatically unsubscribe on receipt or claim authenticated sender ownership of links.

Cleanup tools are opt-in. Without ENABLE_CLEANUP_TOOLS=true the unsubscribe and Junk tools aren't offered at all.

Read-only mode. READ_ONLY=true disables draft, Junk-move, and unsubscribe action tools. With cleanup tools on, unsubscribe-header inspection remains available and makes no web requests.

Settings

Project status

Development

npm test

Tests never log in to a real account.

Background

This server applies the lessons from building yahoo-mail-mcp, a full-featured Yahoo Mail MCP server: most real use came down to summarizing and drafting replies, and every extra tool was surface area an agent didn't need.

License

MIT. See LICENSE.