Graph Mail MCP

一个用于 Microsoft 365 邮件的本地 stdio Model Context Protocol 服务器。它通过 Microsoft Graph 提供受控的 Outlook/Exchange Online 搜索、读取、线程、附件和草稿工作流。

它从不发送、删除、移动、复制、归档或将邮件标记为已读。原始 Graph URL、原始 OData 以及不受限制的 Graph 请求均不对外暴露。

要求

• 装有 Microsoft Edge 的 Windows

• Node.js 22+

• 具有 Exchange Online 的 Microsoft 365 工作或学校账户

• 委派的 Mail.ReadWrite 权限

默认禁用个人 Microsoft 账户。共享邮箱额外需要 Exchange 委派和 Mail.ReadWrite.Shared 权限。

安装

git clone https://github.com/hanhandly/graph-mail-mcp.git
Set-Location graph-mail-mcp
npm ci
npm run build
Copy-Item config.example.json config.local.json

config.local.json 会被 Git 忽略。在身份验证前请先检查它，尤其是 tenant、allowedMailboxScopes 和共享邮箱设置。

身份验证

node dist\cli.js -c config.local.json doctor
node dist\cli.js -c config.local.json auth login --account-hint user@contoso.com
node dist\cli.js -c config.local.json auth status

登录会打开一个独立的 Microsoft Edge 配置文件，并使用 Graph Explorer 进行委派身份验证。Playwright 会点击 登录，选择提示的账户，并检查所需的邮件权限是否已被同意。如果已同意，身份验证会自动继续；否则 CLI 会告知用户需要授予哪个权限。Playwright 从不点击 同意。MFA 和同意确认仍由用户控制。auth status 仅返回元数据，从不显示令牌。

配置 MCP 客户端

在客户端的 MCP 配置中使用绝对路径：

{
  "mcpServers": {
    "graph-mail": {
      "command": "node",
      "args": [
        "C:\\Tools\\graph-mail-mcp\\dist\\cli.js",
        "-c",
        "C:\\Tools\\graph-mail-mcp\\config.local.json",
        "serve"
      ],
      "cwd": "C:\\Tools\\graph-mail-mcp"
    }
  }
}

某些客户端使用不同的外部键，但 command、args 和 cwd 的值相同。将 -c <config-path> 放在 serve 之前。服务器使用 stdio，不打开网络端口。

重启 MCP 客户端，然后调用：

1. mail_auth_status

2. mail_list_folders

3. mail_search_messages

工具

草稿更新仅限于由此 MCP 创建和注册的草稿。没有发送工具。

安全

Graph 传输使用默认拒绝的防火墙策略和类型化请求编译器。令牌存储在仓库之外，默认使用 Windows DPAPI 保护。日志和工具响应不得暴露访问令牌、Cookie 或授权头。

Graph Explorer 可能返回先前已同意给其共享应用程序的权限。服务器拒绝 Mail.Send 并限制运行时请求，但需要严格最小权限令牌的部署应使用专用的应用注册或受限的身份验证提供程序。

参见 安全、工具参考、配置示例 和 架构。