Mail-MCP is a stdio MCP server that lets an AI assistant read, organise, clean up and unsubscribe from mail in a personal Outlook.com / Hotmail / Live mailbox via Microsoft Graph.
Browse folders — mail_list_folders returns the folder tree with total and unread counts (accepts folders by name, path, well-known name or id).
Create folders — mail_create_folder makes a folder at root or under a parent, idempotently (existing folder just returned).
Search and read mail — mail_search lists/searches messages newest-first, filtered by exact sender, date range or unread only, with a query full-text option (subject/body/sender) and cursor pagination (max 100 per page); mail_get_message returns one message's full text body (truncated at 25,000 chars), recipients, attachment flag, web link and detected unsubscribe options.
Triage at scale — mail_senders_summary scans a whole folder (thousands of messages in seconds, cached per session) and aggregates by sender: volume, unread count, latest message and available unsubscribe method, sorted by volume.
File messages — mail_move moves up to 500 messages to any folder, returning old → new id mappings (ids change on move).
Delete safely — mail_delete sends messages to Deleted Items by default (recoverable); permanent: true purges irreversibly.
Bulk-clean a sender — mail_bulk_by_sender moves or deletes every message from one exact address in a folder, with dryRun: true to preview the match count first.
Unsubscribe from newsletters — mail_unsubscribe cascades through RFC 8058 one-click HTTPS POST → mailto: email → returns a browser URL for manual completion, or none if no header exists; it deletes nothing.
Safe by default — deletions are reversible unless explicitly made permanent, bulk actions support dry runs, no generic send tool exists (Mail.Send is only used for mailto: unsubscribes), and every tool ships strict input/output schemas plus MCP annotations (readOnlyHint, destructiveHint, …) so hosts can auto-approve read-only calls.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Mail-MCP Check my inbox for unread newsletters and unsubscribe me."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A small, focused MCP server that lets Claude (Claude Desktop, Cowork, Claude Code or any MCP client) work on a personal Outlook.com / Hotmail / Live mailbox through Microsoft Graph: read and search mail, file it into folders, delete it, and unsubscribe from newsletters.
Built for one job: clean up an overflowing personal inbox with an AI assistant, safely.
Nine tools, all prefixed mail_:
Tool | What it does |
| Folder tree with total / unread counts |
| Create a folder (idempotent) |
| List / search messages (sender, date range, unread, full text), paginated |
| Full content of one message + detected unsubscribe options |
| Aggregate a whole folder by sender: volume, latest message, available unsubscribe method |
| Move up to 500 messages to a folder |
| Move to Deleted Items by default, |
| Move or delete every message from one sender ( |
| RFC 8058 one-click POST → |
Design choices:
Safe by default. Deletion goes to Deleted Items (visible and restorable in Outlook). Permanent deletion requires an explicit flag. Bulk actions support dryRun.
Efficient on big mailboxes. mail_senders_summary scans thousands of messages in a few seconds (1,000-item pages, minimal $select) and only fetches headers for the top senders through $batch.
No generic send tool. The Mail.Send permission is used solely to send mailto: unsubscribe requests.
Every tool ships a strict input schema, an output schema and MCP annotations (readOnlyHint, destructiveHint, …) so hosts can auto-approve read-only calls.
Related MCP server: outlook-mcp
Node.js 22 or newer.
A personal Microsoft account (outlook.com, hotmail.com, live.com, msn.com).
A free Microsoft Entra app registration (5 minutes, below). Password-based IMAP was switched off for personal accounts in September 2024, so an OAuth app is the only supported way in.
No Azure subscription is needed for a public client app.
Go to https://entra.microsoft.com and sign in with your personal Microsoft account.
Identity → Applications → App registrations → New registration.
Fill in:
Name: Mail-MCP
Supported account types: Personal Microsoft accounts only
Redirect URI: platform Mobile and desktop applications, value http://localhost
Click Register and copy the Application (client) ID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
Under Authentication, make sure http://localhost is listed under "Mobile and desktop applications" and Allow public client flows is Yes.
Under API permissions, add Microsoft Graph delegated permissions: Mail.ReadWrite, Mail.Send, User.Read, offline_access. No admin consent is needed; you consent at first sign-in.
No client secret is created: the server is a public client using the authorization code flow with PKCE.
No install needed, npx fetches the package from npm (@rixtay/mail-mcp, the installed command is mail-mcp):
MAIL_MCP_CLIENT_ID=<your-client-id> npx -y @rixtay/mail-mcp loginOr from a clone:
git clone https://github.com/Rixtayz/Mail-MCP.git
cd Mail-MCP
npm install && npm run build
MAIL_MCP_CLIENT_ID=<your-client-id> npm run loginThe login command opens your system browser, signs you in with Microsoft, then stores the token cache in ~/.mail-mcp/token-cache.json (file mode 600). Tokens refresh silently for 90 rolling days. If a tool ever answers "Token expired", run the same command again.
Environment variable | Purpose |
| Required. Application (client) ID from step 1 |
| Optional. Token cache location |
Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or %APPDATA%\Claude\claude_desktop_config.json on Windows), reachable through Settings → Developer → Edit Config.
{
"mcpServers": {
"mail": {
"command": "npx",
"args": ["-y", "@rixtay/mail-mcp"],
"env": {
"MAIL_MCP_CLIENT_ID": "<your-client-id>"
}
}
}
}If Claude Desktop cannot find npx (it does not inherit your shell PATH), use absolute paths instead: "command": "/absolute/path/to/node", "args": ["/absolute/path/to/Mail-MCP/dist/index.js"].
Quit Claude Desktop completely and start it again. Logs: ~/Library/Logs/Claude/mcp-server-mail.log.
Cowork runs local MCP servers only in local sessions, not in cloud sessions.
claude mcp add --scope user --env MAIL_MCP_CLIENT_ID=<your-client-id> --transport stdio mail -- npx -y @rixtay/mail-mcp"Summarise the senders in my inbox and flag the newsletters."
"Unsubscribe me from every newsletter I haven't opened in six months, then move their messages to Deleted Items."
"Create an Invoices folder and move everything from billing@vendor.com into it."
"Show me the latest email from my bank."
Typical flow: mail_senders_summary → the assistant proposes a list, you confirm → mail_unsubscribe(lastMessageId) per newsletter (when the answer is method: "browser", the assistant opens the URL in its browser and finishes there) → mail_bulk_by_sender(action: "delete").
npm test # vitest: header parsing, Graph retry/batch/pagination, service with a mocked Graph
npm run typecheck
npm run inspect # MCP Inspector against dist/index.jsLayout:
src/index.ts CLI entry point: `mail-mcp` serves stdio, `mail-mcp login` signs in
src/login.ts interactive sign-in flow
src/server.ts builds the McpServer and registers the tools
src/auth.ts MSAL public client, file-based token cache
src/graph.ts Graph client: bearer auth, 429/503 retry, pagination, $batch in chunks of 20
src/mail.ts business logic (folders, search, sender summary, move/delete, unsubscribe cascade)
src/unsubscribe.ts List-Unsubscribe / List-Unsubscribe-Post parsing, RFC 8058 one-click POST
src/tools/*.ts tool definitions (zod v4 schemas, annotations)Stack: @modelcontextprotocol/server v2, zod v4, @azure/msal-node v6, html-to-text.
Message ids change whenever a message changes folder. mail_move and mail_delete return the old → new id mapping.
A normal delete is a move to Deleted Items. Graph's own DELETE would drop the item into Recoverable Items, which is invisible in Outlook, so it is deliberately not used.
Microsoft throttles Outlook to 10,000 requests per 10 minutes per mailbox and 4 concurrent requests. Batches are serialised and retried on 429.
mail_search with query (full text) cannot be combined with the other filters (Graph limitation) and tops out at a few hundred results.
Whether an unsubscribe actually takes effect is up to the sender. One-click and mailto: send the request; the assistant's browser handles the rest.
The authority is login.microsoftonline.com/consumers. With common, refresh tokens for personal accounts are rejected after the first refresh.
Bug reports, fixes and focused new tools are welcome: see CONTRIBUTING.md. Please never paste real email content, addresses or tokens in an issue. Found a way the server could leak mail or tokens, or act without being asked? Please report it privately, as described in SECURITY.md.
Release history: CHANGELOG.md.
MIT
Move or delete EVERY message from a sender (exact address) in a folder (Inbox by default). Use dryRun: true first to learn how many messages match. Deletion goes to Deleted Items unless permanent: true.
Inputs: from (required), action (required), dryRun, folder, +2 more. Returns: dryRun, failed, matched, succeeded
Create an Outlook folder (at the root or under a parent). Idempotent: if a folder with the same name already exists it is returned without error. Example: { name: "Newsletters" } or { name: "2025", parent: "Invoices" }.
Inputs: name (required), parent. Returns: folder, created
Delete one or more messages (up to 500 ids). By default messages go to Deleted Items (recoverable with mail_search folder=deleteditems then mail_move; their id changes). permanent: true deletes irreversibly: only use it when the user explicitly asks for it.
Inputs: ids (required), permanent. Returns: moved, failed, succeeded
Return the full content of one message (body converted to text, recipients, attachment flag, web link) plus the unsubscribe options found in its headers (https, mailto, one-click). The body is truncated at 25,000 characters.
Inputs: id (required). Returns: to, body, message, webLink, +3 more
List every folder of the Outlook.com mailbox with its path, total message count and unread count. Call it before filing messages to learn which folders exist. Other tools accept a folder by display name ("Invoices"), by path ("Archive/2024"), by well-known name (inbox, deleteditems, junkemail, archive) or by id.
Inputs: no named parameters. Returns: folders
Move one or more messages (up to 500 ids) to a folder (name, path or id). Used for filing. NOTE: Outlook assigns a new id to every moved message; the moved result maps old id → new id. To move every message from a sender, prefer mail_bulk_by_sender.
Inputs: ids (required), folder (required). Returns: moved, failed, succeeded
List messages of a folder (Inbox by default), newest first, with filters: exact sender, date range, unread only. query runs a full-text search (subject, body, sender) and cannot be combined with the other filters. Returns a compact summary (id, sender, subject, date, preview); use mail_get_message for the full content. To page, pass cursor back verbatim. For a whole-mailbox view by sender, prefer mail_senders_summary.
Inputs: from, limit, query, since, +4 more. Returns: count, items, nextCursor
KEY TOOL FOR TRIAGE. Scans a whole folder (Inbox by default) and aggregates messages by sender: count, unread, latest message, and for the top senders the available unsubscribe method (oneClick / https / mailto). Sorted by volume. The scan is cached for the session. Follow up with mail_unsubscribe(lastMessageId) and mail_bulk_by_sender(address).
Inputs: top, since, folder. Returns: scanned, senders, totalSenders
Try to unsubscribe from the mailing list of a message, in order: (1) RFC 8058 one-click HTTPS POST, (2) automatic email to the List-Unsubscribe mailto address, (3) otherwise returns method: "browser" with the URL to open in a browser to finish manually, (4) method: "none" when no header exists. Deletes nothing. Preferably pass the lastMessageId returned by mail_senders_summary.
Inputs: id (required). Returns: ok, url, from, detail, +3 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 9 tools
Each tool targets a clearly distinct operation: folders, individual message retrieval, search, sender aggregation, move/delete by ID, bulk by sender, and unsubscribe. Overlap between search and sender summary is explicitly addressed by their descriptions and intended use cases.
The mail_ prefix and snake_case style are consistent throughout, and most names use a verb_noun pattern. A few names like mail_senders_summary and mail_bulk_by_sender are noun/adjective phrases rather than clear verb-first names, which is a minor deviation.
Nine tools is a well-scoped count for a mailbox management server. Each tool covers a meaningful operation without redundancy or unnecessary bloat.
The toolset covers the core mailbox triage workflow well: search, read, summarize, move, delete, bulk-manage, and unsubscribe. Missing operations like folder deletion/renaming, sending messages, or marking messages as read are notable but do not break the primary use case.
Manage Microsoft 365 email, calendar, contacts and inbox rules via the Graph API with OAuth 2.0.
Search Gmail and Outlook, save drafts, manage email rules, and view email stats.
Read, send, file and search email in any Gmail, Microsoft 365 or IMAP mailbox, plus its calendar.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
