内容
# gmail-attachments-mcp
<!-- mcp-name: io.github.zayansalman/gmail-attachments-mcp -->
一款专注于将Gmail附件下载到磁盘的[模型上下文协议](https://modelcontextprotocol.io)服务器（和独立的命令行工具）。三个工具，读取权限的OAuth范围，无额外攻击面。
由于Claude Desktop中托管的`claude.ai Gmail`连接器仅返回附件**ID和元数据** — 而不是实际的字节。该服务器填补了任何MCP客户端（Claude Code，Claude Desktop，Cursor，Cline等）的这一空白，也可以用作cron作业和shell脚本的普通命令行工具。
如果您曾经使用[`@GongRzhe/Gmail-MCP-Server`](https://github.com/GongRzhe/Gmail-MCP-Server)（1.1k★，存档日期2026-03-03）进行附件下载工作流程，那么这是一个专注于该功能的最小化继承者。
## 功能
- **3个MCP工具** — `gmail_search`，`gmail_download_thread_attachments`，`gmail_download_latest_matching`。仅此而已。
- **读取权限的OAuth范围** (`gmail.readonly`) — 无法发送、删除或修改邮件。
- **既是MCP服务器又是独立命令行工具** — 相同的代码，相同的身份验证令牌，两种界面。
- **环境变量驱动的配置** — `GMAIL_MCP_CREDENTIALS`，`GMAIL_MCP_TOKEN`，`GMAIL_MCP_DEFAULT_DEST_DIR`。
- **适合cron** — 授权后，缓存的刷新令牌允许无头作业无限期运行。
## 安装
```bash
pip install gmail-attachments-mcp
# 或者，使用uv：
uv tool install gmail-attachments-mcp
```
## 一次性设置（约10分钟）
您需要一个Google Cloud OAuth客户端。服务器完全在您的机器上运行；不会有任何数据离开。
1. 使用您要下载附件的Gmail账户登录[Google Cloud Console](https://console.cloud.google.com/)。
2. 创建一个项目（或选择现有的项目）。
3. 启用Gmail API：[console.cloud.google.com/apis/library/gmail.googleapis.com](https://console.cloud.google.com/apis/library/gmail.googleapis.com)。
4. 在**APIs & Services → OAuth consent screen**下配置OAuth同意屏幕：
- **Google Workspace**用户：用户类型 = **内部**（无需应用验证）。
- **个人Gmail**用户：用户类型 = **外部**。在“测试用户”下添加您的Gmail地址作为测试用户。
5. **APIs & Services → Credentials → + Create credentials → OAuth client ID**
- 应用程序类型：**桌面应用程序**
- 下载JSON文件。
6. 运行设置：
```bash
gmail-attachments-mcp setup --import-credentials ~/Downloads/client_secret_*.json
```
将打开一个浏览器窗口用于OAuth同意。同意后，在`~/.config/gmail-attachments-mcp/token.json`（或 `$XDG_CONFIG_HOME/gmail-attachments-mcp/`）缓存刷新令牌。
验证：
```bash
gmail-attachments-mcp status
gmail-attachments-mcp search "has:attachment newer_than:7d" --max 3
```
参见 [docs/setup-google-oauth.md](docs/setup-google-oauth.md) 获取截图和故障排除信息。
## 从Claude Code使用
```bash
claude mcp add --scope user gmail-attachments gmail-attachments-mcp -- serve
```
然后在任何Claude Code会话中：
> 使用gmail-attachments MCP将`careers@example.com`的最新简历下载到 `~/CVs`。
## 从Claude Desktop使用
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` （Mac）或 `%APPDATA%/Claude/claude_desktop_config.json` （Windows）：
```json
{
"mcpServers": {
"gmail-attachments": {
"command": "gmail-attachments-mcp",
"args": ["serve"]
}
}
}
```
重启Claude Desktop。详见 [docs/claude-desktop.md](docs/claude-desktop.md)。
## 从Cursor / Cline / Continue / 其他使用
任何支持stdio服务器的MCP客户端。指向相同的 `gmail-attachments-mcp serve` 命令。参见 [docs/other-clients.md](docs/other-clients.md)。
## 从shell或cron使用
```bash
# 搜索
gmail-attachments-mcp search "from:noreply@stripe.com has:attachment newer_than:30d"
# 下载特定线程中的所有附件
gmail-attachments-mcp thread 19db831fab15b507 --dest ~/Invoices
# 从最新匹配项下载，仅限PDF
gmail-attachments-mcp latest "from:hr@example.com has:attachment" --dest ~/CVs --ext .pdf,.docx
```
cron示例 — 每小时拉取简历附件：
```cron
0 * * * * /usr/local/bin/gmail-attachments-mcp latest "to:careers@example.com 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的标准查询语法。
```json
[
{
"thread_id": "19db831fab15b507",
"subject": "Folon Q3 2026 Quarterly Product Recap",
"sender": "Manon Muhtasin Rahman <manon@example.com>",
"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覆盖变量 |
## 安全
- **令牌存储**：刷新令牌写入 `~/.config/gmail-attachments-mcp/token.json`，权限为 `0600`。任何具有您账户shell访问权限的人都可以读取您的Gmail。像对待密码一样对待该文件。
- **OAuth范围**：默认为 `gmail.readonly`。无法发送、删除或修改邮件。如果您更改 `$GMAIL_MCP_SCOPES`，则需要对后果负责。
- **凭证文件**：您的OAuth客户端密钥JSON **不是**密码 — 它标识您的应用给Google。但永远不要提交它。包含的 `.gitignore` 阻止了常见的 filenames。
- **OAuth客户端**：您的客户端位于**您的**Google Cloud项目中。没有中央服务器，没有遥测数据，没有数据离开您的机器。
## 故障排除
**`No valid Gmail token` 当从Claude Desktop / cron调用时**
第一次OAuth流程需要浏览器。在可以打开浏览器的终端中运行 `gmail-attachments-mcp setup`。后续运行使用缓存的刷新令牌。
**`Token has been expired or revoked`**
刷新令牌只要您至少每6个月使用一次且不撤销，就保持有效，在 [myaccount.google.com/permissions](https://myaccount.google.com/permissions) 处撤销。重新授权：
```bash
gmail-attachments-mcp setup --reauth
```
**`Access blocked: This app's request is invalid`**
对于个人Gmail，您的OAuth同意屏幕需要在**测试用户**下列出您的地址。工作区用户应选择**内部**受众以避免此问题。
**`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](https://github.com/GongRzhe/Gmail-MCP-Server) | 完整邮箱 | 19 | **2026-03-03 存档** |
| [shinzo-labs/gmail-mcp](https://github.com/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](docs/setup-google-oauth.md)。
- **您的令牌存储位置：** `~/.config/gmail-attachments-mcp/token.json`（模式 `0600`）。删除它以在本地撤销；完全撤销请访问 [myaccount.google.com/permissions](https://myaccount.google.com/permissions)。
- **没有托管/SaaS选项** — 所有内容都在本地运行；您的邮件永远不会触及第三方服务器。
## 相关工具
这是针对Google Workspace数据的小型专注的本地MCP服务器系列的一部分，托管的连接器无法访问这些数据：
- **gmail-attachments-mcp** — 将Gmail附件字节下载到磁盘（此仓库）
- **[google-drive-comments-mcp](https://github.com/zayansalman/google-drive-comments-mcp)** — 读取Docs/Sheets/Slides上的评论线程
- **[google-drive-files-mcp](https://github.com/zayansalman/google-drive-files-mcp)** — 移动/组织Drive文件
它们可以共享一个OAuth登录或保持隔离 — 参见每个仓库的设置。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
## 贡献
欢迎提出问题和PR。在提交前运行 `pytest` 和 `ruff check src tests`。
```bash
git clone https://github.com/zayansalman/gmail-attachments-mcp
cd gmail-attachments-mcp
pip install -e ".[dev]"
pytest
```
