Outlook Mail

io.github.Pepebitsv1.0.1更新于 Oct 8, 2026

Read, search, send and clean up Outlook.com / Hotmail mail through Microsoft Graph.

已验证STDIO仅桌面Productivity & WorkflowCommunication & Collaboration

概览

AI 生成的概览

让助手通过 Microsoft Graph 读取、搜索、发送和整理 Outlook.com 或 Microsoft 365 邮件。

功能
以 stdio 方式在本地运行，通过 OAuth 设备代码流登录 Microsoft Graph。工具涵盖浏览文件夹、列出和用 KQL 搜索邮件、以纯文本读取正文、列出和下载附件、发送邮件、创建草稿、回复、转发、移动、标记、标记已读和删除邮件，还包括查找简报、退订以及用收件箱规则屏蔽发件人。批量操作最多接受 50 个邮件 id。
适用场景
当你希望助手处理 Outlook、Hotmail 或 Microsoft 365 邮箱时使用：分拣和搜索邮件、起草或发送回复、下载附件，或清理简报和不需要的发件人。只读模式适合只查看、不做任何更改的场景。
运行要求
需要 Node.js 24 或更高版本以及一个 Microsoft 账户；个人账户可使用共享应用，工作或学校账户需要自行注册 Azure 应用。可选环境变量包括 OUTLOOK_CLIENT_ID、OUTLOOK_TENANT、OUTLOOK_SCOPES、OUTLOOK_TOKEN_CACHE、OUTLOOK_READ_ONLY、OUTLOOK_DOWNLOAD_DIR 和 OUTLOOK_GRAPH_BASE_URL。登录是交互式的：login 工具返回网址和一次性代码，也可在终端运行 auth 命令。
安装前请注意
会修改数据的工具会立即发送邮件，delete_message 配合 permanent: true 不可恢复；不确定时优先使用只读模式或 create_draft。令牌缓存保存在本地，同意页面可能显示未验证发布者警告。邮件内容是不可信输入，可能尝试提示注入，因此发送或删除操作需人工确认。收件箱规则需要 MailboxSettings.ReadWrite 权限。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Outlook Mail，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

[outlook-mcp]

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 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 under 3 MB)
  • 🗂️ 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

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

Claude Desktop

Add to claude_desktop_config.json and restart Claude Desktop:

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

Codex (OpenAI)

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

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

toml
[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.

VariableDefaultDescription
OUTLOOK_CLIENT_IDshared outlook-mcp appApplication (client) ID of your own Azure app registration (optional).
OUTLOOK_TENANTconsumersAuthority tenant: consumers (personal), organizations (work/school), common (both) or a tenant GUID.
OUTLOOK_SCOPESUser.Read Mail.ReadWrite Mail.Send MailboxSettings.ReadWrite offline_accessSpace-separated delegated Graph scopes requested at sign-in.
OUTLOOK_TOKEN_CACHE~/.config/outlook-mcp/token-cache.jsonWhere the MSAL token cache is stored (file mode 0600).
OUTLOOK_READ_ONLYfalseWhen true, send/move/delete/flag/mark tools are not registered at all.
OUTLOOK_DOWNLOAD_DIR~/DownloadsThe only directory attachments may be written to.
OUTLOOK_DEFAULT_TOP20Default page size for list/search tools (1-100).
OUTLOOK_MAX_BODY_CHARS20000Maximum body characters returned by get_message.
OUTLOOK_GRAPH_BASE_URLhttps://graph.microsoft.com/v1.0Graph endpoint (change for national clouds).
LOG_LEVELinfodebug, info, warn or error (written to stderr).

🔐 Authentication

bash
npx -y @pepebits/outlook-mcp auth      # device code sign-in; prints a URL and a codenpx -y @pepebits/outlook-mcp whoami    # silent token + GET /menpx -y @pepebits/outlook-mcp logout    # removes accounts and deletes the token cache 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 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 ...".

🛠️ 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.

ScopeUsed for
User.ReadSign-in and whoami
Mail.ReadWriteReading, searching, moving, flagging and deleting messages
Mail.Sendsend_mail, replies, forwards and mailto unsubscribe
MailboxSettings.ReadWriteInbox rules: list_rules, create_rule, delete_rule, block_sender
offline_accessRefresh token, so you only sign in once

💡 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).

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

ToolMutatingDescription
loginnoStart a device code sign-in; returns the URL and code (force to sign in again).
auth_statusnoSigned in, pending sign-in or signed out.
logoutnoSign out and delete the local token cache.
list_foldersnoList mail folders or child folders (parentFolderId, includeHidden).
list_messagesnoList messages, newest first, with filters (unreadOnly, from, since, until, hasAttachments) and nextLink paging.
search_messagesnoKQL full-text search with nextLink paging.
get_messagenoFull message with recipients, flags and body (format text/html, maxChars).
list_attachmentsnoAttachment metadata for a message.
download_attachmentnoSave an attachment into OUTLOOK_DOWNLOAD_DIR (writes locally only; no overwrite unless overwrite: true).
send_mailyesSend an email, optionally with local attachments under 3 MB.
create_draftyesCreate a draft without sending.
reply_messageyesReply or reply-all (replyAll).
forward_messageyesForward to new recipients.
move_messageyesMove to a folder; returns the new id. Accepts id or ids (up to 50).
mark_readyesMark read or unread. Accepts id or ids (up to 50).
flag_messageyesflagged, complete or notFlagged. Accepts id or ids (up to 50).
delete_messageyesMove to Deleted Items, or permanent: true to delete irreversibly. Accepts id or ids (up to 50).
get_unsubscribe_infonoShow how to leave the mailing list a message came from (List-Unsubscribe).
unsubscribeyesLeave a mailing list: RFC 8058 one-click, else a mailto request, else returns the link. Accepts id or ids (up to 50).
find_newslettersnoScan a folder (folderId, maxMessages up to 2000, excludeDomains, includeNoUnsubscribe), group by sender and report mailing lists with their unsubscribe method, most frequent first.
list_rulesnoList inbox rules.
create_ruleyesCreate an inbox rule from fromAddresses / senderContains / subjectContains with action move, delete, markRead or junk.
delete_ruleyesDelete an inbox rule by id.
block_senderyesBlock addresses and/or domains with a rule that moves their future mail to Deleted Items.

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.

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

👁️ 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 locally 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). Review actions that send or delete.

🩺 Troubleshooting

SymptomFix
AADSTS7000218 (client assertion / secret required)Enable Allow public client flows in Azure -> Manage -> Authentication -> Settings.
AADSTS50020 or wrong tenantThe account type does not match OUTLOOK_TENANT. Use consumers for personal, organizations for work/school, common for both, and make sure the app registration supports that account type.
"Not signed in or session expired"Ask the assistant to call login, or run npx -y @pepebits/outlook-mcp auth.
Search returns "Invalid search query"search_messages uses KQL, e.g. from:alice subject:"report" hasattachments:true. Graph returns at most about 250 results per search, and results are not sorted.
"Message not found" after a moveMessage ids change when a message is moved. Use the newId returned by move_message or list the folder again.
"Access denied for inbox rules"Add MailboxSettings.ReadWrite in Azure -> API permissions, make sure it is in OUTLOOK_SCOPES, then run npx -y @pepebits/outlook-mcp auth again.
Access denied / consent requiredAdd the missing delegated permission, or ask an admin for consent.
Server does not start in a clientCheck stderr logs; if you use your own app, OUTLOOK_CLIENT_ID must be set via .env or the client's env block.

🧑‍💻 Development

bash
git clone https://github.com/Pepebits/outlook-mcp.gitcd outlook-mcpnpm installcp .env.example .env        # optionalnpm run buildnpm test

Run it from source in your MCP client:

bash
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

  • 📅 Calendar support (Calendars.ReadWrite)
  • 📦 Large attachments through upload sessions
  • 👥 Contacts

🤝 Contributing

Issues and pull requests are welcome.

bash
npm installnpm run typechecknpm testnpm run build

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

📄 License

MIT

来源：README.md，提交 8505169

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v1.0.1最新Oct 8, 2026