AI导哈

Gmail只读调查工具

一个安全的基于Python的CLI工具和MCP服务器，用于调查Gmail账户，保证只读访问，提供Gmail集成。

  • by AdamFerguson06
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 AdamFerguson06/gmail-mcp

使用说明

Gmail阅读器-只读Gmail调查工具

关键安全提示：此工具仅供阅读。它无法发送、修改或删除电子邮件。

基于Python的安全CLI工具 MCP服务器 用于调查具有保证只读访问权限的Gmail帐户。通过模型上下文协议（MCP）为Claude桌面/代码提供无缝的Gmail集成。使用与经过实战考验的安全架构相同的安全架构 google_ads_控制器.

特性

  • 双接口：用于Claude集成的CLI工具+MCP服务器
  • 只读：带有的Gmail API gmail.readonly 仅范围
  • 安全：测试强制安全护栏（13项测试，全部通过）
  • 完全访问：搜索、阅读、列出、导出电子邮件和帖子
  • 速率限制：10请求/秒（可配置Gmail API配额管理）
  • OAuth 2.0：在中使用凭据进行安全身份验证 ~/.env

安全保障

三层安全架构

  1. OAuth作用域限制 （第1层）

    • 仅 gmail.readonly 在OAuth流期间授予作用域
    • 无法在OAuth级别发送、修改或删除电子邮件
    • 谷歌强制执行这一规定——无法绕过

  2. 测试强制护栏 （第2层）

    • test_read_only_guardrail.py 每次提交时扫描所有源文件
    • 如果发现变异方法，CI将失败(.send(), .modify(), .trash(), .delete())
    • 如果在中找到非只读作用域，则CI失败 auth.py

  3. 防止秘密泄露 （第3层）

    • test_secret_leak.py 扫描硬编码凭据
    • .gitignore 块 .env 和 *.json 凭证文件
    • 如果在代码中发现机密，CI将失败

什么得到承诺，什么留在当地

✅ 承诺 （安全）：

  • 源代码（无秘密）
  • 安全测试（扫描仪）
  • 文档

❌ 从不承诺 （被封锁 .gitignore +测试）：

  • ~/.env （OAuth凭据）
  • *.json 文件(client_secret.json, token.json)
  • 硬编码的秘密

安装

先决条件

  • Python 3.9+（仅CLI）或Python 3.11+（用于MCP服务器）
  • 启用Gmail API的谷歌云项目
  • OAuth 2.0凭据（桌面应用程序）

设置步骤

  1. 克隆或创建项目目录:

    cd ~/Documents/gmail_reader

  2. 创建虚拟环境:

    python3.9 -m venv .venv
source .venv/bin/activate

  3. 安装包:

    pip install -e .

  4. 获取OAuth凭据 （一次性）：

    • 首选 谷歌云控制台
    • 创建新项目或选择现有项目
    • 启用Gmail API（API和服务→ 图书馆→ Gmail API→ 启用）
    • 创建凭据（API和服务→ 凭证→ 创建凭据→ OAuth客户端ID）
    • 应用程序类型： 桌面应用
    • 下载JSON文件

  5. 将凭据添加到 ~/.env:

    • 打开下载的JSON文件
    • 添加 ~/.env:
      GMAIL_CLIENT_ID=YOUR_CLIENT_ID.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=GOCSPX-YOUR_CLIENT_SECRET
    • 删除下载的JSON文件 复制值后

  6. 运行OAuth身份验证 （一次性）：

    gmail-reader auth
    • 打开浏览器进入谷歌同意屏幕
    • 授予以下权限 只读Gmail访问
    • 刷新令牌自动保存到 ~/.env

  7. 测试:

    gmail-reader list --max 10

MCP服务器设置（克劳德集成）

MCP服务器允许Claude直接访问您的Gmail，而无需手动CLI命令。

快速设置

  1. 确保已安装Python 3.11+ （MCP需要Python 3.10+）：

    python3.11 --version  # Should be 3.11 or higher

  2. 安装gmail阅读器 （如果还没有）：

    cd ~/Documents/gmail_reader
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .

  3. 配置MCP服务器 在Claude桌面配置中：

    对于 克劳德代码 （VSCode扩展），添加到您的MCP设置中：

    {
  "mcpServers": {
    "gmail": {
      "command": "/Users/YOUR_USERNAME/Documents/gmail_reader/.venv/bin/python",
      "args": ["-m", "gmail_reader.mcp_server"],
      "env": {}
    }
  }
}

    对于 Claude桌面应用程序，添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

    {
  "mcpServers": {
    "gmail": {
      "command": "/Users/YOUR_USERNAME/Documents/gmail_reader/.venv/bin/python",
      "args": ["-m", "gmail_reader.mcp_server"]
    }
  }
}

  4. 重新启动克劳德 加载MCP服务器

MCP工具可用

配置后，Claude可以使用这些工具：

工具 说明
gmail_list 列出最近的电子邮件，包括发件人、主题、日期、片段
gmail_search 使用Gmail查询运算符搜索（发件人：、主题：、后缀：等）
gmail_read 阅读完整的电子邮件内容（页眉+正文）
gmail_labels 列出所有Gmail标签（收件箱、发送、用户创建）
gmail_thread 查看线程/对话中的所有消息
gmail_export 将日期范围内的电子邮件导出为JSON

克劳德互动示例

User: "Show me emails from boss@company.com in the last week"
Claude: [Uses gmail_search with query "from:boss@company.com after:2026/02/10"]

User: "Read the most recent email from Google"
Claude: [Uses gmail_list to find ID, then gmail_read to show full content]

User: "How many unread emails do I have?"
Claude: [Uses gmail_search with query "is:unread"]

MCP服务器故障排除

错误：“身份验证错误”

  • 跑 gmail-reader auth 终端优先
  • 确保 ~/.env 有 GMAIL_REFRESH_TOKEN

MCP服务器未加载

  • 检查Python路径是否正确（使用绝对路径）
  • 重新启动Claude桌面/代码
  • 检查Claude日志是否有错误

用法

认证

# One-time OAuth setup (opens browser)
gmail-reader auth

列出最近的电子邮件

# List 50 most recent emails (default)
gmail-reader list

# List 100 most recent emails
gmail-reader list --max 100

# Output as JSON
gmail-reader list --max 10 --output json

搜索电子邮件

Gmail支持强大的搜索运营商：

# Search by sender
gmail-reader search "from:boss@company.com"

# Search by date range
gmail-reader search "after:2026/02/01 before:2026/02/17"

# Search by subject
gmail-reader search "subject:invoice"

# Search unread emails
gmail-reader search "is:unread"

# Combine multiple criteria
gmail-reader search "from:google.com is:unread after:2026/02/01" --max 100

# Search with label
gmail-reader search "label:important"

# Output as JSON
gmail-reader search "from:noreply" --max 5 --output json

搜索运算符:

  • from: -发件人电子邮件地址
  • to: -收件人电子邮件地址
  • subject: -主题行关键字
  • after: -日期范围开始（YYYY/MM/DD）
  • before: -日期范围结束（YYYY/MM/DD）
  • is:unread / is:read -读取状态
  • label: -Gmail标签
  • has:attachment -有附件

阅读完整电子邮件

# Read email (snippet view)
gmail-reader read <message-id>

# Read email (full body)
gmail-reader read <message-id> --format full

# Output as JSON
gmail-reader read <message-id> --output json

导出电子邮件

# Export all emails in date range to JSON
gmail-reader export --start-date 2026-01-01 --end-date 2026-02-17

# Custom output file
gmail-reader export --start-date 2026-01-01 --end-date 2026-02-17 --file my_emails.json

备注：将大数据流导出到文件，以避免内存溢出。

列出Gmail标签

# List all labels
gmail-reader labels

# Output as JSON
gmail-reader labels --output json

查看电子邮件主题

# View all messages in a thread
gmail-reader threads <thread-id>

# Output as JSON
gmail-reader threads <thread-id> --output json

速率限制

  • Gmail API配额：250单位/用户/秒
  • 默认：10个请求/秒（50个单位/秒，限制的20%）
  • 自动重试：429（超出速率限制）错误

速率限制已在中配置 src/gmail_reader/client.py:

_RATE_LIMIT_RPS = 10  # Requests per second

项目结构

gmail_reader/
├── src/gmail_reader/
│   ├── __init__.py          - Package metadata
│   ├── config.py            - Load ~/.env credentials
│   ├── auth.py              - OAuth 2.0 flow
│   ├── client.py            - Gmail API client + rate limiting
│   ├── queries.py           - Query constants & helpers
│   ├── __main__.py          - CLI entry point
│   ├── mcp_server.py        - MCP server for Claude integration
│   └── reports.py           - Email parsing & formatting
├── tests/
│   ├── test_config.py                - Config loading tests
│   ├── test_read_only_guardrail.py   - Security scanner (mutations)
│   └── test_secret_leak.py           - Security scanner (credentials)
├── pyproject.toml           - Package configuration
├── .gitignore               - Blocks .env and *.json
└── README.md                - This file

安全最佳实践

凭证管理

  1. 中的所有凭据 ~/.env -永远不要使用git
  2. 删除OAuth JSON 添加后 ~/.env
  3. 刷新令牌轮换 -如果令牌过期，请重新运行 gmail-reader auth

验证只读状态

运行安全测试以验证没有突变：

pytest tests/test_read_only_guardrail.py -v
pytest tests/test_secret_leak.py -v

OAuth作用域验证

检查 src/gmail_reader/auth.py:

SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"]

仅 gmail.readonly 应该出席。如果修改，安全测试将失败。

故障排除

“错误：未找到GMAIL_REFRESH_TOKEN”

解决方案：运行 gmail-reader auth 以进行身份验证。

“刷新令牌已过期”

解决方案：重新运行 gmail-reader auth 以获得新的刷新令牌。

“超出费率限制”

解决方案：等待10秒。工具会自动重试一次。如果持续存在，请增加延迟 client.py.

“没有名为‘gmail_reader’的模块”

解决方案：安装软件包 pip install -e . 从项目根。

OAuth JSON已下载，但找不到

解决方案：检查 ~/Downloads/client_secret_*.json.打开文件并复制 client_id 和 client_secret 到 ~/.env.

发展

运行测试

# All tests
pytest tests/ -v

# Security tests only
pytest tests/test_read_only_guardrail.py tests/test_secret_leak.py -v

# Config tests only
pytest tests/test_config.py -v

添加新功能

关键的：从不添加写入操作。安全测试将失败。

如果需要添加新的读取操作：

  1. 更新 ALLOWED_GMAIL_METHODS 在 tests/test_read_only_guardrail.py
  2. 仅使用 .list() 或 .get() 方法
  3. 跑 pytest tests/test_read_only_guardrail.py 验证

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

相关项目

支持

对于问题或疑问，请在GitHub存储库中创建问题。

最后更新: 2026-02-17 版本: 0.1.0

相关 MCP