How do I install Mail?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Mail need an API key?

The publisher lists these environment variables: MAIL_MCP_CLIENT_ID, MAIL_MCP_CACHE_PATH.

When was Mail last checked?

Last checked 2026-11-09. Personal Outlook.com / Hotmail inbox: read, search, file, delete, unsubscribe via Microsoft Graph.

Mail MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @rixtay/[email protected]

Credentials from the publisher

MAIL_MCP_CLIENT_ID — Application (client) ID of your Microsoft Entra app registration (see README). Run `npx -y @rixtay/mail-mcp login` once to sign in.
MAIL_MCP_CACHE_PATH — Token cache location. Defaults to ~/.mail-mcp/token-cache.json.

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1MAIL_MCP_CLIENT_ID=<value> MAIL_MCP_CACHE_PATH=<value> claude mcp add io.github.rixtayz-mail-mcp -- npx -y @rixtay/mail-mcp@0.1.2

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.rixtayz-mail-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@rixtay/[email protected]"8      ],9      "env": {10        "MAIL_MCP_CLIENT_ID": "<value>",11        "MAIL_MCP_CACHE_PATH": "<value>"12      }13    }14  }15}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.1.2

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

Mail-MCP

Mail-MCP: AI-powered inbox control for Outlook

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.

Tools

Nine tools, all prefixed mail_:

Tool	What it does
`mail_list_folders`	Folder tree with total / unread counts
`mail_create_folder`	Create a folder (idempotent)
`mail_search`	List / search messages (sender, date range, unread, full text), paginated
`mail_get_message`	Full content of one message + detected unsubscribe options
`mail_senders_summary`	Aggregate a whole folder by sender: volume, latest message, available unsubscribe method
`mail_move`	Move up to 500 messages to a folder
`mail_delete`	Move to Deleted Items by default, `permanent: true` to purge
`mail_bulk_by_sender`	Move or delete every message from one sender (`dryRun` supported)
`mail_unsubscribe`	RFC 8058 one-click POST → `mailto:` email → otherwise a URL for the assistant to open in a browser

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.

Inbox chaos to inbox zero with Mail-MCP: analyze senders, review, unsubscribe, organize, and safely delete

Requirements

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.

1. Register an app in Microsoft Entra (once, free)

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.

2. Sign in

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 login

Or 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 login

The 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
`MAIL_MCP_CLIENT_ID`	Required. Application (client) ID from step 1
`MAIL_MCP_CACHE_PATH`	Optional. Token cache location

3. Connect to Claude Desktop / Cowork

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.

4. Connect to Claude Code

claude mcp add --scope user --env MAIL_MCP_CLIENT_ID=<your-client-id> --transport stdio mail -- npx -y @rixtay/mail-mcp

5. Example prompts

"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 [email protected] 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").

Development

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.js

Layout:

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.

Things worth knowing

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.

Contributing

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.

License

MIT

Mail

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Mail?

Does Mail need an API key?

What transport does Mail use?

When was Mail last checked?

Documentation

Mail-MCP

Tools

Requirements

1. Register an app in Microsoft Entra (once, free)

2. Sign in

3. Connect to Claude Desktop / Cowork

4. Connect to Claude Code

5. Example prompts

Development

Things worth knowing

Contributing

License