gmail-attachments-mcp

gmail-attachments-mcp

一个专注于将 Gmail 附件下载到磁盘的 Model Context Protocol 服务（以及独立 CLI）。提供三个工具，使用只读 OAuth 权限范围，不包含多余功能。

这是因为 Claude Desktop 中托管的 claude.ai Gmail 连接器只会返回附件的ID 和元数据，而不会返回实际文件内容。此服务为任何 MCP 客户端（Claude Code、Claude Desktop、Cursor、Cline 等）填补了这一空缺，也可作为普通 CLI 用于 cron 作业和 shell 脚本。

如果你曾使用 @GongRzhe/Gmail-MCP-Server（1.1k★，已于 2026-03-03 归档）来下载附件，那么这是一个专注于该单一功能的精简后继项目。

功能特性

• 3 个 MCP 工具 — gmail_search、gmail_download_thread_attachments、gmail_download_latest_matching。这就是全部 API。
• 只读 OAuth 权限范围（gmail.readonly）— 无法发送、删除或修改邮件。
• 既可作为 MCP 服务，也可作为独立 CLI 使用 — 相同代码、相同认证令牌，两种使用方式。
• 由环境变量驱动的配置 — GMAIL_MCP_CREDENTIALS、GMAIL_MCP_TOKEN、GMAIL_MCP_DEFAULT_DEST_DIR。
• 适用于 cron — 授权后，缓存的刷新令牌可让无头作业无限期运行。

安装

pip install gmail-attachments-mcp
# or, with uv:
uv tool install gmail-attachments-mcp

一次性设置（约 10 分钟）

你需要一个 Google Cloud OAuth 客户端。此服务完全在你的计算机上运行；任何数据都不会离开本机。

1. 使用你要下载其附件的 Gmail 账号登录 Google Cloud Console。
2. 创建一个项目（或选择现有项目）。
3. 启用 Gmail API：console.cloud.google.com/apis/library/gmail.googleapis.com。
4. 在 APIs & Services → OAuth consent screen 下配置 OAuth 同意屏幕：
   • Google Workspace 用户：User type = Internal（无需应用验证）。
   • 个人 Gmail 用户：User type = External。在“Test users”下将你自己的 Gmail 地址添加为测试用户。
5. APIs & Services → Credentials → + Create credentials → OAuth client ID
   • Application type：Desktop app
   • 下载 JSON 文件。
6. 运行设置：

gmail-attachments-mcp setup --import-credentials ~/Downloads/client_secret_*.json

浏览器窗口会打开以供 OAuth 授权。授权后，刷新令牌会缓存到 ~/.config/gmail-attachments-mcp/token.json（或 $XDG_CONFIG_HOME/gmail-attachments-mcp/）。

验证：

gmail-attachments-mcp status
gmail-attachments-mcp search "has:attachment newer_than:7d" --max 3

截图和故障排除请参阅 docs/setup-google-oauth.md。

在 Claude Code 中使用

claude mcp add --scope user gmail-attachments gmail-attachments-mcp -- serve

然后在任意 Claude Code 会话中：

使用 gmail-attachments MCP，将 [email protected] 发来的最新简历下载到 ~/CVs。

在 Claude Desktop 中使用

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）或 %APPDATA%/Claude/claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "gmail-attachments": {
      "command": "gmail-attachments-mcp",
      "args": ["serve"]
    }
  }
}

重启 Claude Desktop。详情请参阅 docs/claude-desktop.md。

在 Cursor / Cline / Continue / 其他客户端中使用

任何支持 stdio 服务的 MCP 客户端都可以使用。将其指向相同的 gmail-attachments-mcp serve 命令。请参阅 docs/other-clients.md。

在 shell 或 cron 中使用

# Search
gmail-attachments-mcp search "from:[email protected] has:attachment newer_than:30d"

# Download every attachment from a specific thread
gmail-attachments-mcp thread 19db831fab15b507 --dest ~/Invoices

# Download from the latest match, only PDFs
gmail-attachments-mcp latest "from:[email protected] has:attachment" --dest ~/CVs --ext .pdf,.docx

Cron 示例 — 每小时拉取简历附件：

0 * * * * /usr/local/bin/gmail-attachments-mcp latest "to:[email protected] has:attachment newer_than:2d" --dest ~/CVs --ext .pdf,.docx >> ~/.cache/gmail-attachments-mcp.log 2>&1

3 个 MCP 工具

gmail_search(query, max_results=10)

返回包含附件文件名的会话摘要。使用 Gmail 的标准查询语法。

[
  {
    "thread_id": "19db831fab15b507",
    "subject": "Folon Q3 2026 Quarterly Product Recap",
    "sender": "Manon Muhtasin Rahman <[email protected]>",
    "date": "Thu, 23 Apr 2026 08:35:00 +0600",
    "snippet": "Hi everyone, Attached is...",
    "message_count": 1,
    "attachment_count": 1,
    "attachment_filenames": ["Folon Quarterly Report Q3 2026.pdf"]
  }
]

gmail_download_thread_attachments(thread_id, dest_dir?, extensions?)

将一个会话中的所有附件下载到磁盘。每个文件返回 path、size_bytes、mime_type、original_filename。

gmail_download_latest_matching(query, dest_dir?, extensions?)

便捷工具：通过一次调用搜索并下载最新匹配项中的附件。

配置

所有路径都可以通过环境变量覆盖。

变量	默认值	说明
GMAIL_MCP_CREDENTIALS	~/.config/gmail-attachments-mcp/credentials.json	OAuth 客户端密钥 JSON
GMAIL_MCP_TOKEN	~/.config/gmail-attachments-mcp/token.json	缓存的刷新令牌
GMAIL_MCP_DEFAULT_DEST_DIR	~/Downloads	默认下载目标目录
GMAIL_MCP_SCOPES	https://www.googleapis.com/auth/gmail.readonly	OAuth 范围（以逗号分隔）
XDG_CONFIG_HOME	~/.config	标准 XDG 覆盖项

安全性

• 令牌存储：刷新令牌会以 0600 权限写入 ~/.config/gmail-attachments-mcp/token.json。任何能通过 shell 访问你账户的人都能读取你的 Gmail。请像保护密码一样保护此文件。
• OAuth 范围：默认值为 gmail.readonly。无法发送、删除或修改邮件。如果你更改了 $GMAIL_MCP_SCOPES，后果由你自行承担。
• 凭据文件：你的 OAuth 客户端密钥 JSON 不是密码，而是用于向 Google 标识你的应用。但切勿提交该文件。随附的 .gitignore 会屏蔽常见文件名。
• OAuth 客户端：你的客户端位于你自己的 Google Cloud 项目中。没有中央服务器，也没有遥测数据，任何内容都不会离开你的设备。

故障排除

从 Claude Desktop / cron 调用时出现 No valid Gmail token 首次 OAuth 流程需要浏览器。请在可打开浏览器的终端中运行一次 gmail-attachments-mcp setup。之后的运行会使用缓存的刷新令牌。

Token has been expired or revoked 只要每 6 个月至少使用一次刷新令牌，且不在 myaccount.google.com/permissions 撤销，它就会保持有效。重新进行身份验证：

gmail-attachments-mcp setup --reauth

Access blocked: This app's request is invalid 对于个人 Gmail，你的 OAuth 同意屏幕需要在 Test users 下列出你的地址。Workspace 用户应选择 Internal 受众以避免此问题。

HttpError 403: Request had insufficient authentication scopes 你更改了 $GMAIL_MCP_SCOPES，但没有重新授权。请运行 gmail-attachments-mcp setup --reauth。

与其他 Gmail MCP 服务的比较

服务	范围	工具	维护状态
Anthropic 托管的 claude.ai Gmail	读写、托管	许多	积极维护，但不提供附件字节数据
GongRzhe/Gmail-MCP-Server	完整邮箱	19	已于 2026-03-03 归档
shinzo-labs/gmail-mcp	完整邮箱	~30	积极维护
gmail-attachments-mcp（本项目）	只读	3	积极维护

如果你想要一个小巧、专注且只读的工具，请选择此项目。如果你还需要发送邮件、管理标签、草稿、会话等，请选择功能更全面的项目。

身份验证——使用你自己的 Google OAuth 客户端

没有 API 密钥，也没有随附的机密信息。该服务通过你自己创建的 OAuth 客户端连接到你的 Google 账户，并在本地缓存刷新令牌。作者无法访问你的任何数据。

• 为什么要使用自己的客户端？ Google 的受限范围（此处为 gmail.readonly）不能在共享应用中重新分发，未经验证的共享应用最多只能有 100 位用户。“使用自己的 OAuth 客户端”是个人数据 MCP 服务的标准模式。
• **你需要准备什么：**一个免费的 Google Cloud 项目、已启用的 Gmail API、OAuth 同意屏幕以及桌面 OAuth 客户端。完整指南 → docs/setup-google-oauth.md。
• 令牌存储位置：~/.config/gmail-attachments-mcp/token.json（权限为 0600）。删除该文件可在本地撤销令牌；如需完全撤销，请前往 myaccount.google.com/permissions。
• 不提供托管 / SaaS 选项——所有内容都在本地运行；你的邮件不会经过第三方服务器。

相关工具

这是面向 Google Workspace 数据的一组小型专用本地 MCP 服务的一部分，可处理托管连接器无法提供的数据：

• gmail-attachments-mcp — 将 Gmail 附件内容下载到磁盘 (本仓库)
• google-drive-comments-mcp — 读取 Docs/Sheets/Slides 中的评论串
• google-drive-files-mcp — 移动/整理 Drive 文件

它们可以共用一个 OAuth 登录，也可以彼此隔离——请参阅各仓库的设置说明。

许可证

MIT。请参阅 LICENSE。

贡献

欢迎提交问题和 PR。提交前请运行 pytest 和 ruff check src tests。

git clone https://github.com/zayansalman/gmail-attachments-mcp
cd gmail-attachments-mcp
pip install -e ".[dev]"
pytest