zenrith-fluxman/gmail-mcp-server

# Gmail MCP Server (安全加固分支) 一个安全加固的 Gmail [模型上下文协议](https://modelcontextprotocol.io/)服务器。专为 Claude Code、Claude Desktop 或任何兼容 MCP 的客户端设计。 ## 安全模型 本分支围绕以下原则构建：**除非您明确选择启用，否则读取您电子邮件的 AI 助手不应能够发送、删除或创建转发规则**。 ### 安全标志 危险工具默认通过 `src/tools.ts` 中的编译时标志**禁用**： | 标志 | 默认值 | 控制项 | |------|---------|----------| | `ENABLE_SEND_EMAIL` | `false` | `send_email`, `reply_all` | | `ENABLE_DELETE_EMAIL` | `false` | `delete_email`, `batch_delete_emails` | | `ENABLE_FILTER_CREATION` | `false` | `create_filter`, `create_filter_from_template` | 要启用某项功能，请在 `src/tools.ts` 中将标志更改为 `true` 并重新构建 (`npm run build`)。 ### 提示注入防护 所有返回给 AI 的电子邮件内容均被包裹在随机的加密边界中： ``` --- UNTRUSTED EMAIL CONTENT [a1b2c3d4e5f6...] --- (email body here) --- END UNTRUSTED EMAIL CONTENT [a1b2c3d4e5f6...] --- ``` 该边界通过每次调用 `crypto.randomUUID()` 生成，如果其出现在内容中则会被剥离，这使得恶意电子邮件无法伪造关闭标记。 ### 锁定的 OAuth Scopes OAuth scopes 在 `src/scopes.ts` 中被**硬编码**（`--scopes` CLI 标志将被忽略）： ``` const HARDCODED_SCOPES = ["gmail.modify"]; ``` - `gmail.modify` 涵盖读取、草稿、归档和标签操作 - `gmail.settings.basic` 被**排除**（它会启用自动转发规则） - `gmail.send` 和 `gmail.compose` 被**排除** 要更改 scopes，请编辑 `src/scopes.ts` 中的 `HARDCODED_SCOPES` 并重新进行身份验证。 ### 额外加固 - **CRLF 头注入防护** —— 清理所有用户提供的 header 值 - **路径遍历防护** —— 附件下载会验证解析后的路径 - **OAuth 回调仅绑定到 127.0.0.1** —— 认证期间无网络暴露风险 - **凭证文件以 0o600 权限写入** —— 仅限所有者访问 ## 设置 ### 1. 获取 OAuth 凭证 您需要一个 `gcp-oauth.keys.json` 文件。可以通过以下方式获取： - **创建您自己的 Google Cloud 项目**（参见下方的 [Google Cloud 设置](#google-cloud-project-setup)），或者 - **从已有项目的人那里获取该文件**（他们只需在其 OAuth 同意屏幕中将您的 Google 帐号添加为测试用户） ### 2. 安装与认证 ``` git clone https://github.com/zenrith-fluxman/gmail-mcp-server.git cd gmail-mcp-server npm install && npm run build # 放置你的 OAuth 密钥 (如果需要，创建该目录) mkdir -p ~/.gmail-mcp cp /path/to/gcp-oauth.keys.json ~/.gmail-mcp/ # 认证 (打开浏览器，使用你的 Google 账号登录) node dist/index.js auth ``` 凭证将保存到 `~/.gmail-mcp/credentials.json`。每个用户拥有自己的凭证文件 —— OAuth 密钥文件是共享的，但您的令牌是私有的。 ### 3. 配置您的 MCP 客户端 **Claude Code** (`~/.claude.json` 或 `.mcp.json`)： ``` { "mcpServers": { "gmail": { "command": "node", "args": ["/path/to/gmail-mcp-server/dist/index.js"] } } } ``` **Claude Desktop** (`claude_desktop_config.json`)： ``` { "mcpServers": { "gmail": { "command": "node", "args": ["/path/to/gmail-mcp-server/dist/index.js"] } } } ``` ## 可用工具 在默认安全标志下，提供 15 种工具。标有锁的工具需要启用相应的安全标志。 ### 读取 | 工具 | 描述 | |------|-------------| | `search_emails` | 使用 Gmail 查询语法搜索电子邮件。仅返回元数据（无正文）。 | | `bulk_read_emails` | 一次读取多封电子邮件。返回完整正文及附件元数据。 | | `download_attachment` | 将电子邮件附件下载到本地文件系统。 | ### 会话 | 工具 | 描述 | |------|-------------| | `get_thread` | 检索会话中的所有邮件（按时间顺序）。 | | `list_inbox_threads` | 列出与查询匹配的会话，包含摘要和邮件数量。 | | `get_inbox_with_threads` | 列出会话，可选择展开完整的邮件内容。 | ### 撰写 | 工具 | 描述 | |------|-------------| | `draft_email` | 创建电子邮件草稿（支持 HTML、附件、会话）。 | | `modify_email` | 为电子邮件添加/移除标签。 | | `batch_modify_emails` | 批量修改多封电子邮件的标签。 | | `archive_emails` | 将电子邮件从收件箱中移除（可选择应用跟踪标签）。 | ### 标签 | 工具 | 描述 | |------|-------------| | `list_email_labels` | 列出所有 Gmail 标签（系统标签 + 用户标签）。 | | `create_label` | 创建新标签。 | | `update_label` | 更新标签的名称或可见性。 | | `delete_label` | 删除用户创建的标签。 | | `get_or_create_label` | 按名称获取标签，如果不存在则创建。 | ### 默认禁用 | 工具 | 安全标志 | 风险 | |------|-------------|------| | `send_email` | `ENABLE_SEND_EMAIL` | 立即发送电子邮件 | | `reply_all` | `ENABLE_SEND_EMAIL` | 发送给所有收件人 | | `delete_email` | `ENABLE_DELETE_EMAIL` | 永久删除，无法撤消 | | `batch_delete_emails` | `ENABLE_DELETE_EMAIL` | 批量永久删除 | | `create_filter` | `ENABLE_FILTER_CREATION` | 可能设置自动转发 | | `create_filter_from_template` | `ENABLE_FILTER_CREATION` | 可能设置自动转发 | ### 过滤器工具（只读，始终可用） | 工具 | 描述 | |------|-------------| | `list_filters` | 列出所有 Gmail 过滤器。 | | `get_filter` | 获取特定过滤器的详细信息。 | | `delete_filter` | 删除过滤器。 | ## 重新认证 要更改 scopes 或刷新凭证： ``` rm ~/.gmail-mcp/credentials.json node dist/index.js auth ``` ## 故障排除 - **未找到 OAuth 密钥** —— 请确保 `gcp-oauth.keys.json` 位于 `~/.gmail-mcp/` 目录中 - **"invalid_grant" 错误** —— 令牌已过期。请删除 `~/.gmail-mcp/credentials.json` 并重新认证。 - **端口 3000 被占用** —— 在运行认证之前释放该端口 (`lsof -i :3000`) - **"Not a test user" 错误** —— 请在 OAuth consent screen > Audience > Test users 下添加该 Google 帐号 ## Google Cloud 项目设置 如果您需要创建自己的 OAuth 凭证： 1. 前往 [Google Cloud Console](https://console.cloud.google.com/) 2. 创建一个新项目（或选择一个现有项目） 3. 启用 **Gmail API** 4. 前往 **APIs & Services > Credentials** 5. 点击 **Create Credentials > OAuth client ID** 6. 选择 **Desktop app**，为其命名，然后点击 **Create** 7. 下载 JSON 文件并将其重命名为 `gcp-oauth.keys.json` 如果您的应用处于 "Testing" 模式（默认），请在 **OAuth consent screen > Audience > Test users** 下添加授权用户。 ## 许可证 MIT (详见 [LICENSE](LICENSE)) ## 致谢 - [GongRzhe](https://github.com/GongRzhe) —— 原版 Gmail MCP 服务器 - [ArtyMcLabin](https://github.com/ArtyMcLabin) —— 维护的分支，包含回复线程、send-as 别名和 CI 加固 - 来自 [@JF10R](https://github.com/JF10R)、[@MaxGhenis](https://github.com/MaxGhenis)、[@nicholas-anthony-ai](https://github.com/nicholas-anthony-ai)、[@tansanDOTeth](https://github.com/tansanDOTeth) 的安全贡献

标签：AI安全, API安全, Chat Copilot, CISA项目, Claude集成, CRLF注入防御, GitHub Advanced Security, Gmail, GNU通用公共许可证, JSONLines, JSON输出, MCP Server, MITM代理, Node.js, OAuth2.0, TypeScript, 加密边界, 安全加固, 安全插件, 安全标志, 提示注入防护, 权限最小化, 模型上下文协议, 电子邮件安全, 网络安全, 自定义脚本, 范围锁定, 路径遍历防护, 隐私保护, 零信任, 默认拒绝