Multi-Account Gmail

gmail-mcp

一个 MCP 服务，只需一次连接即可读取你所有 Gmail 账号中的邮件。

大多数 Gmail 集成（包括原生连接器）在每次 OAuth 授权中只绑定一个账号：连接第二个收件箱，就会断开第一个账号。gmail-mcp 可同时授权任意数量的账号。一个 Google Cloud 客户端即可授权所有账号，每个账号都以一行数据的形式存储在本地 SQLite 文件中，每个工具都接受 account 参数，以便路由到正确的邮箱。 search_all_accounts 可通过单次查询扫描所有账号。

Python 3.12+ · MIT · stdio MCP 服务 + 身份验证 CLI · 本地 SQLite 令牌存储

它旨在让你完全掌控：通过 stdio 在进程内运行，将令牌存储在一个可供检查、复制或删除的 SQLite 文件中，只与 Google 和你的 MCP 客户端通信，不会硬编码任何密钥。

它可以读取、搜索、创建草稿和添加标签，但不会发送邮件——create_draft 会留下草稿供你自行发送。这是有意采用的默认行为（原因详见安全模型，并非绝对限制；如果你需要自动发送，只需稍作扩展，或使用其他服务。

---

目录

• 30 秒了解核心思路
• 设计说明
• 工具
• 架构
• 身份与身份验证模型
  • OAuth 模型
  • 多账号模型
  • 令牌生命周期
  • 无头身份验证流程
• 安全模型
• 安装
• 快速入门
• 配置
• 注册到 MCP 客户端
• 开发
• 项目布局
• 许可证

---

30 秒了解核心思路

通过 CLI 一次性授权 N 个账号。之后，每个工具都接受 account 参数，而 search_all_accounts 会一次性搜索所有账号：

search_all_accounts(query="invoice newer_than:30d")

  ── [email protected] ───────────────────────────────
  from: [email protected]    subject: Invoice #4821    (id 18f...)

  ── [email protected] ─────────────────────────────────
  from: [email protected]        subject: March invoice     (id 19a...)

一次查询即可搜索所有收件箱，每条结果都标注所属账号并包含邮件 ID——因此 Agent 可以接着调用 read_message(account, id) 或 create_draft(...)。

---

设计说明

一个 OAuth 客户端，多个收件箱。 一个 Google Cloud 项目和一个 client_secret.json 即可授权所有账号。添加第十个收件箱的流程与添加第一个时一样简单，只需一条命令。

简单可靠的存储。 令牌保存在 ~/.gmail-mcp/ 下的一个 SQLite 文件中。不需要守护进程、密钥环依赖或云服务。复制文件即可备份；删除一行即可撤销某个账号的授权；可使用任何 SQLite 工具检查文件内容。

最小权限。 使用四个细分作用域——gmail.readonly、gmail.compose、gmail.modify、gmail.settings.basic，绝不请求完整邮箱作用域 https://mail.google.com/。它可以读取邮件、创建草稿、添加标签和管理过滤器；绝不会发送邮件，并且它创建的过滤器无法将邮件转发到账号之外。

适合无头环境。 身份验证流程假设服务可能没有浏览器：它会打印授权 URL、绑定固定端口，并要求你通过 SSH 转发重定向。桌面环境下也能正常使用。

---

工具

除 list_accounts 和 search_all_accounts 外，每个工具都需要一个 account （电子邮件地址）。对于未知账户，会返回错误并列出已授权的账户。

工具	参数	返回值
list_accounts	—	已授权账户及其上次使用时间。用于发现有效的 account 值。
search_messages	account、query、max_results=20	带有 id 的邮件摘要（Gmail 搜索语法）。
read_message	account、message_id、format="full"、max_body_chars?	解码后的邮件头、纯文本正文（必要时会去除 HTML）以及附件元数据。正文默认截断；传入 max_body_chars=0 可获取完整正文。
read_thread	account、thread_id、max_body_chars?	线程中的所有邮件，按顺序排列。每封邮件的正文默认截断；传入 max_body_chars=0 可获取完整正文。
download_attachments	account、message_id、index?	将邮件附件保存到磁盘并返回绝对路径。使用 read_message 中显示的 #N 指定附件；省略 index 则下载所有附件。下载根目录固定，不接受目标路径参数。拒绝危险文件类型，以及垃圾邮件标记邮件中的任何附件。
search_all_accounts	query、max_results_per_account=10	在所有账户中各执行一次搜索，每条结果均标注所属账户。
create_draft	account、body、to?、subject?、cc?、bcc?、html=false、reply_to_message_id?、reply_all=false、from_addr?	草稿（不会发送）。返回草稿 id。若指定 reply_to_message_id，草稿会作为回复加入该邮件的线程：收件人、主题、In-Reply-To、References 和线程 id 均从该邮件获取，且 to/subject 可作为可选覆盖项。若未指定，则必须提供 to 和 subject。from_addr 为已验证的代发别名设置 From 头；默认使用账户地址。
list_drafts	account、max_results=20	账户中的草稿 id。
list_labels	account	账户的标签（名称 + id）。
modify_labels	account、选择范围（message_id | message_ids | query）、add?、remove?	对选定范围（单个 id、id 列表或查询匹配的所有邮件）添加/移除标签，每次调用批量处理 1000 封。通用修改工具：归档 = 移除 INBOX，标记为已读 = 移除 UNREAD，加星标 = 添加 STARRED。
trash	account、选择范围（message_id | message_ids | query）	将选定范围移至垃圾箱（可在 30 天内恢复；不会永久删除）。选择范围为空时拒绝执行。
bulk_action	account、action、选择范围（message_id | message_ids | query）	对 modify_labels 的友好动词封装。action ∈ archive/unarchive/mark_read/mark_unread/star/unstar/spam/unspam/trash/untrash。每次调用批量处理 1000 封；选择范围为空时拒绝执行。
read_messages	account、message_ids | query、max_results=25	一次调用批量读取多封邮件的完整内容（而非调用 N 次 read_message）。
count_messages	query、account?、all_accounts=false	统计匹配项，不获取内容 — 批量操作前用于检查影响范围。all_accounts 会返回各账户的统计明细及总数。
list_filters	account	账户的过滤器：id、条件、操作（标签 id 显示为名称）。
create_filter	account、以下字段之一：from_address/to_address/subject/query/has_attachment，以及一个操作（archive/mark_read/delete/star 或 add_labels/remove_labels）	应用于收到的邮件的服务端规则。不能转发到其他账户。
delete_filter	account、filter_id	按 id 移除过滤器（不影响已执行过滤操作的邮件）。

---

架构

flowchart TD
    subgraph client[Your machine]
        Agent[MCP client / agent]
        CLI[gmail-mcp-auth CLI]
        Server[gmail-mcp stdio server]
        Store[("SQLite<br/>~/.gmail-mcp/tokens.db")]
        Secret["client_secret.json<br/>one OAuth client"]
    end
    Google[Google OAuth + Gmail API]

    CLI -->|"loopback OAuth, once per account"| Google
    CLI -->|"store refresh token"| Store
    Secret -.-> CLI
    Agent -->|"tool call (account=...)"| Server
    Server -->|"look up + refresh creds"| Store
    Secret -.-> Server
    Server -->|"read / draft / label"| Google
    Server --> Agent

每个账户只需通过命令行授权一次（需要浏览器）。 此后，stdio 服务会直接从 SQLite 读取令牌，按需刷新访问令牌， 并将其保存回数据库。本节其余部分将详细解释“这样设计的原因”。

---

身份与身份验证模型

了解 gmail-mcp 如何通过单个 OAuth 客户端向 Gmail 进行身份验证、管理多个账号、定期刷新令牌，以及如何在无头服务器上为账号授权。如果你只想快速开始，请跳转到快速入门。

OAuth 模型

gmail-mcp 使用 Google “桌面应用” OAuth 客户端进行身份验证（按 OAuth 2.0 术语称为已安装应用），并通过 google-auth-oauthlib 的 InstalledAppFlow 助手驱动流程。

为什么使用已安装应用／桌面客户端。 已安装应用运行在最终用户控制的设备上，因此 OAuth 将其视为公共客户端：下载的 client_secret.json 中的 client_secret 不被视为机密。这适合本地 CLI／桌面工具的信任模型——没有服务器端组件可以真正保守秘密，安全性依赖于用户控制重定向（环回地址），而不是秘密信息的保密性。这也是 Google 为命令行和桌面工具推荐的客户端类型。

环回重定向流程。 你在浏览器中批准授权后，Google 会将授权码重定向到 http://localhost:<port>/，由一个临时的小型 HTTP 服务（通过 InstalledAppFlow.run_local_server 启动）接收。gmail-mcp 将其固定到一个端口（默认 8765，可通过 GMAIL_MCP_OAUTH_PORT 覆盖），并使用 open_browser=False 运行，因此可在没有浏览器的设备上工作——请参阅无头身份验证路径。

请求的范围。 四个细分范围——绝不请求完整邮箱范围 https://mail.google.com/：

范围	授予的权限
gmail.readonly	读取邮件和元数据：搜索邮件／邮件会话、读取正文、列出标签和草稿。只读——无法修改任何内容。
gmail.compose	创建、更新和管理草稿。仅供 create_draft 使用。
gmail.modify	为邮件添加／移除标签。供 modify_labels 使用。
gmail.settings.basic	列出、创建和删除过滤器。供 list_filters／create_filter／delete_filter 使用。不授予更改转发地址的权限（该权限属于 gmail.settings.sharing，此处未请求）。

不会请求 gmail.send。没有此权限，凭据就无法通过 Gmail API 发送邮件——仅支持草稿是授权范围的属性，并非只是省略了某个工具。同样也不会请求 gmail.settings.sharing，因此过滤器无法将邮件转发到其他地址。范围列表集中定义在 src/gmail_mcp/config.py 的 SCOPES 中。

向现有安装添加过滤器范围： 扩大 SCOPES 不会追溯授予已授权的账号。每个账号都必须重新运行 gmail-mcp-auth add，以重新同意新的范围；在此之前，过滤器工具会返回 403 insufficient scope 错误。

多账号模型

• 一个 OAuth 客户端可授权多个账号。 创建一个 Google Cloud 项目和一个“桌面应用” OAuth 客户端，然后针对每个 Gmail 账号各运行一次授权流程，每次登录你要添加的账号。单个 client_secret.json 可以授权任意数量的账号。
• 每个账号在 SQLite 中对应一行。 每个已授权账号都存储在 accounts 表中（~/.gmail-mcp/tokens.db，可通过 GMAIL_MCP_DB 覆盖），并以邮箱地址为键。每行包含长期有效的刷新令牌、最新的访问令牌数据、已授予的范围和时间戳。
• 工具调用通过 account 参数路由。 除 list_accounts 和 search_all_accounts 外，每个工具都需要 account。服务会查找该邮箱，为其创建凭据，并以该账号调用 Gmail API。对于未知账号，会返回明确错误并列出已授权的账号。search_all_accounts 会遍历所有存储的行。

flowchart LR
    Client[MCP client / agent] -->|"[email protected]"| Server[gmail_mcp.server]
    Server --> Store[("accounts table<br/>keyed by email")]
    Store -->|"row [email protected]"| CredsA[Credentials a]
    Store -->|"row [email protected]"| CredsB[Credentials b]
    CredsA --> InboxA["Gmail: [email protected]"]
    CredsB --> InboxB["Gmail: [email protected]"]
    Secret["client_secret.json<br/>one OAuth client"] -.->|"shared by all rows"| CredsA
    Secret -.-> CredsB

令牌生命周期

初始授权（每个账户一次，通过 CLI 完成）。OAuth 流程需要浏览器，而 MCP 工具无法顺畅地控制浏览器，因此授权由 gmail-mcp-auth CLI 负责，而不是通过工具完成。

sequenceDiagram
    actor User
    participant CLI as gmail-mcp-auth add
    participant Browser
    participant Google as Google OAuth + Gmail API
    participant Store as SQLite token store

    User->>CLI: run `gmail-mcp-auth add`
    CLI->>CLI: load client_secret.json,<br/>start loopback server on :8765
    CLI-->>User: print consent URL (open_browser=False)
    User->>Browser: open URL, sign into target account
    Browser->>Google: consent + approve scopes
    Google-->>Browser: redirect with authorization code
    Browser->>CLI: GET http://localhost:8765/?code=...
    CLI->>Google: exchange code for tokens
    Google-->>CLI: access token + refresh token
    CLI->>Google: users.getProfile (discover email)
    Google-->>CLI: emailAddress
    CLI->>Store: upsert(email, refresh_token, token, scopes)
    CLI-->>User: "Authorized and stored: [email protected]"

• CLI 会传入 prompt="consent"，强制签发刷新令牌——Google 只会在用户重新同意时返回刷新令牌。如果没有返回刷新令牌，CLI 会明确报错（前往 https://myaccount.google.com/permissions 撤销应用授权，然后重新运行）。
• 账户邮箱由系统自动发现，而非手动输入：令牌交换后，CLI 会调用 users.getProfile，并使用返回的地址作为存储记录的键。

每次请求时刷新（每次工具调用）。访问令牌的有效期较短（约 1 小时）。每次调用时，服务会为目标账户重新构建凭据，让 google-auth 按需刷新，并将刷新后的数据写回存储。

sequenceDiagram
    participant Client as MCP client / agent
    participant Server as gmail_mcp.server
    participant Store as SQLite token store
    participant Google as Google OAuth + Gmail API

    Client->>Server: tool call ([email protected])
    Server->>Store: get(account) → refresh_token + last token
    Server->>Server: build Credentials
    alt access token still valid
        Server->>Google: Gmail API request
    else access token expired
        Server->>Google: refresh using refresh_token
        Google-->>Server: new access token
        Server->>Store: update_token(account, new blob)
        Server->>Google: Gmail API request
    end
    Google-->>Server: response
    Server->>Store: touch(account) → last_used_at
    Server-->>Client: result (email content wrapped as untrusted)

如果刷新失败（授权已撤销、刷新令牌已过期），服务会抛出 GmailAuthError，并提示“重新运行 gmail-mcp-auth add”，而不是直接崩溃。

测试模式与已发布模式——7 天有效期的注意事项。 常见的意外情况是“运行一周后就不能用了”：

• OAuth 同意屏幕处于测试模式时，只有列出的测试用户可以授权；发给未经验证应用的刷新令牌会在 7 天后过期——你需要每周重新运行 gmail-mcp-auth add。
• 发布应用（同意屏幕 → 发布应用）后，刷新令牌的有效期会变长。Google 会警告应用“未经验证”——对于不进行分发、仅供个人使用的可自托管工具，这种情况完全正常。若要长期使用，请发布应用。SETUP.md 介绍了具体操作步骤。

无头认证流程

通常目标环境是无头服务（没有桌面环境或浏览器），但 OAuth 授权必须在浏览器中完成。此流程可解决这一问题：

• open_browser=False —— CLI 会打印授权 URL，而不是启动浏览器。你可以在自己的笔记本电脑上打开该 URL，并登录要添加的账户。

• 固定的 loopback 端口 —— 获得批准后，Google 会重定向到 http://localhost:<port>/。此处的“localhost”指的是服务端的 loopback 地址，CLI 会在此监听。端口固定（默认为 8765，GMAIL_MCP_OAUTH_PORT），因此可以确定性地进行转发。

• SSH 端口转发 —— 将笔记本电脑上的浏览器连接到服务端的 loopback 地址：

  ssh -L 8765:localhost:8765 you@your-server
  

这样，当重定向到达笔记本电脑上的 localhost:8765 时，SSH 会将其隧道转发到服务端，由 CLI 捕获授权码并完成令牌交换。

---

安全模型

收件箱里满是别人写的文本，因此很容易发生提示词注入。通常用致命三要素来描述——当 Agent 同时具备以下三项时，注入就会造成危险：

flowchart LR
    A[Private data<br/>your mailboxes] --- C{Injection<br/>risk}
    B[Untrusted content<br/>any email you receive] --- C
    D[Egress channel<br/>a way to send data out] --- C
    C -.->|drafts-only removes the obvious one| D
    style D stroke-dasharray: 5 5

邮件阅读器天生具备前两项。以下几项设计选择让第三项保持在低风险水平：

• 创建草稿，而不是发送邮件。 create_draft 是对外操作的上限——没有发送工具，也没有 gmail.send 权限范围。草稿会留在草稿箱，直到由你发送，因此邮件中隐藏的指令无法让 Agent 把你的数据寄到别处。这是合理的默认设置；如果你想启用发送功能，也很容易更改。

• 将邮件内容标记为不可信。 工具返回的消息文本会由单个辅助函数（gmail.py 中的 wrap_untrusted）用 ⟦UNTRUSTED EMAIL CONTENT⟧ 分隔符包裹，并将 ID 保留在分隔符外部，以便工具链调用仍能正常工作。读取工具的说明也会指出，内容是数据，而不是指令。对于多消息响应（搜索结果、邮件会话、跨账号扫描），只会在整个内容块外包裹一次分隔符——而非每条消息各包裹一次——并将每个正文关联到位于分隔符外部的可信 #N ID 清单。这样既能减少分隔符带来的令牌开销，也能确保真实 ID 只出现在可信区域中，避免攻击者将伪造 ID 偷渡到 Agent 会视为权威信息的位置。

• 附件只会下载到一个固定位置，有些附件则完全不会下载。 download_attachments 只会将文件写入 ~/.gmail-mcp/attachments/<message_id>/（GMAIL_MCP_ATTACHMENT_DIR）。这里刻意不提供目标路径参数，因为这会成为任意文件写入原语，邮件中隐藏的指令可能会利用它指向 ~/.zshrc。文件名由攻击者指定，因此会被处理成无害的 ASCII 基本文件名（移除路径分隔符和开头的点、去掉双向覆盖字符、限制长度并添加索引前缀），并在写入前再次检查解析后的路径是否位于根目录下。文件仅允许所有者访问，并使用 O_NOFOLLOW，防止预先放置的符号链接重定向文件。

  文件筛查会在获取任何字节之前进行。以下文件一律拒绝：Gmail 本身会在传输过程中拦截的文件类型（.exe、.jar、.js、.vbs、.iso、.py 等约 50 种类型）、启用宏的 Office 文档、可执行 MIME 类型，以及 Gmail 标记为 SPAM 的邮件中的所有附件。会检查文件名的所有点分后缀，而不只是最后一个，因此 invoice.pdf.exe 也会被拦截。归档文件会被保存，但会标记出来，因为这里无法检查其内部内容。

  这是类型筛查，不是病毒扫描。 Gmail 会在服务器端扫描附件，但不会通过其 API 提供扫描结果。邮件或附件资源上没有恶意软件字段，而且 attachments.get 会提供 Gmail 网页界面不允许下载的字节。这里的检查结果为通过，只表示“不是明显的攻击载体”，绝不意味着“已扫描且安全”。已保存文件的内容仍是不可信的第三方数据。

已知限制。 这只约束此服务的功能范围。如果同一个 Agent 会话还使用了能够访问开放互联网的工具（网页抓取、HTTP），那就是 gmail-mcp 无法处理的独立外传路径——与可任意外传数据的工具搭配使用，会在其他地方重新构成致命三要素。请谨慎选择在同一会话中使用哪些工具。

另外还需说明两点：没有实现审计日志（这是有意不纳入范围），并且没有硬编码任何机密——client_id/client_secret 来自你下载的 client_secret.json，令牌仅存储在本地 SQLite 数据库中。

---

安装

需要 Python 3.12+。PyPI 发行包名称为 multi-account-gmail-mcp（gmail-mcp 这个名称已被占用）；安装后会提供 gmail-mcp 和 gmail-mcp-auth 命令。

# From PyPI
pip install multi-account-gmail-mcp
# or, to get the commands on PATH globally:
uv tool install multi-account-gmail-mcp     # or: pipx install multi-account-gmail-mcp
# or run without installing:
uvx multi-account-gmail-mcp

从源代码安装（用于开发）：

git clone https://github.com/cunicopia-dev/gmail-mcp.git
cd gmail-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .            # add ".[dev]" for ruff + pytest

这会安装两个控制台脚本：gmail-mcp（stdio 服务）和 gmail-mcp-auth（账号授权命令行工具）。

---

快速开始

你需要一个 Google“桌面应用” OAuth 客户端（client_secret.json），并为每个账户授权一次。完整的逐步操作说明——创建 Google Cloud 项目、启用 Gmail API、发布授权同意屏幕，以及无头环境下的 SSH 端口转发步骤——请参阅 docs/SETUP.md。简要步骤如下：

# 1. Drop your downloaded OAuth client here:
mkdir -p ~/.gmail-mcp && mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/client_secret.json

# 2. Authorize an account (prints a URL to open in a browser; repeat per account).
#    On a headless server, SSH in with -L 8765:localhost:8765 first.
gmail-mcp-auth add

# 3. Confirm what's authorized.
gmail-mcp-auth list

# 4. Point your MCP client at the `gmail-mcp` command (see below).

之后可以使用 gmail-mcp-auth remove [email protected] 移除账户。

---

配置

所有配置项均为可选——默认值已设置在 ~/.gmail-mcp/ 下。

变量	默认值	用途
GMAIL_MCP_DB	~/.gmail-mcp/tokens.db	SQLite 令牌存储路径。
GMAIL_MCP_CLIENT_SECRET	~/.gmail-mcp/client_secret.json	下载的 Google OAuth 客户端。
GMAIL_MCP_OAUTH_PORT	8765	授权流程使用的固定环回端口（在无头设备上通过 SSH 转发此端口）。
GMAIL_MCP_ATTACHMENT_DIR	~/.gmail-mcp/attachments	download_attachments 的下载根目录。文件会保存到每条邮件各自的子目录中。这是服务唯一会写入的位置。
GMAIL_MCP_MAX_ATTACHMENT_BYTES	26214400（25 MB）	每个附件的大小上限。Gmail 自身的限制是 25 MB，因此此设置不会拒绝 Gmail 会传送的任何文件。0（或负数）表示不限制。
GMAIL_MCP_MAX_BODY_CHARS	500	read_message/read_thread 的每封邮件正文默认字符数上限。此限制刻意设置得较低，以降低默认读取开销；0（或负数）表示不限制，且每次调用的 max_body_chars 参数会覆盖此设置。

---

在 MCP 客户端中注册

此服务使用 stdio 通信。将客户端的 mcpServers 配置指向 gmail-mcp 命令：

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/gmail-mcp/.venv/bin/gmail-mcp"
    }
  }
}

如果 gmail-mcp 位于 PATH 中，设置 "command": "gmail-mcp" 即可。必要时显式指定路径（有些客户端不会展开 ~）：

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/gmail-mcp/.venv/bin/gmail-mcp",
      "env": {
        "GMAIL_MCP_DB": "/home/you/.gmail-mcp/tokens.db",
        "GMAIL_MCP_CLIENT_SECRET": "/home/you/.gmail-mcp/client_secret.json"
      }
    }
  }
}

---

开发

pip install -e ".[dev]"
ruff check .
pytest                       # 48 tests, no network — the Gmail client is mocked

测试覆盖纯逻辑层——MIME 解析/解码、标签名称→ID 解析、不可信内容包装、输出格式化，以及针对临时 SQLite 数据库的令牌存储增删改查。

---

项目结构

src/gmail_mcp/
  server.py    MCP tool definitions + dispatch + per-account routing
  gmail.py     Gmail service build, token refresh/persist, MIME parse/format,
               wrap_untrusted(), label resolution, MIME message build
  store.py     TokenStore — sqlite3 accounts table CRUD
  auth.py      gmail-mcp-auth CLI: add / list / remove (loopback OAuth)
  config.py    SCOPES + env-overridable paths
docs/
  SETUP.md     step-by-step Google Cloud + account authorization
tests/         store / gmail / server, Gmail client mocked

---

许可证

MIT — 参见 LICENSE。