elzinko/google-mcp-multi-account

# google-mcp-multi-account **将 LLM 代理（Claude Desktop、Cursor、Claude Code 等）连接到多个 Google 账号——Gmail、Drive、Calendar、Docs、Sheets、Tasks——100% 在本地运行。** [](https://github.com/elzinko/google-mcp-multi-account/actions/workflows/ci.yml) [](LICENSE) [](SECURITY.md) [](#安全) [](docs/usage.md) [](https://buymeacoffee.com/elzinko) 本地 **MCP** ([Model Context Protocol](https://modelcontextprotocol.io)) 服务器 ([`bin/google-mcp`](bin/google-mcp)) + 面向 LLM 客户端的 gateway ([`gateway/`](gateway/))；以及供人类使用的 wrapper [`bin/gwsa`](bin/gwsa) 和 Web 管理后台。**没有任何服务在云端运行**：唯一需要访问 Google Cloud 控制台的操作，就是*一次性*创建 OAuth 凭据。 ## 快速开始（3 个步骤） **1 · 配置 Google Cloud 项目**（一次性操作，约 10 分钟）： ``` git clone https://github.com/elzinko/google-mcp-multi-account.git cd google-mcp-multi-account brew install googleworkspace-cli # le CLI gws ln -sf "$PWD/bin/gwsa" "$(brew --prefix)/bin/gwsa" # le wrapper dans le PATH (amorçage) ./scripts/provision-gcp.sh # crée le projet, active les APIs, te guide ``` 该脚本会完成所有可自动化的步骤，并指导你完成 **Google 仅允许手动执行的两个操作**（创建 *Desktop app* 类型的 OAuth 客户端，发布应用），然后妥善保存 `client_secret.json`。GCP 项目依然是一个空壳：没有部署任何内容，0 费用。 详情 / 手动方式：[docs/setup-oauth.md](docs/setup-oauth.md)。 **2 · 安装服务器并连接**（一次性操作）： ``` ./scripts/update.sh ``` 就像安装正式产品一样：通过一条命令获取最新发布版本，将其安装在 **Clone 之外** (`~/.local/share/google-mcp//`)，并将 Claude Desktop 连接到它——不会影响你其他的 MCP 服务器，且会自动备份配置。可安全重复执行：如果没有更新，它会提示“已是最新版本”。 安装在 Clone 之外绝非小事：否则开发过程会在你使用工具时改变其运行状态，且正在开发中的代码可能会访问你的真实账号。 然后**重启 Claude Desktop**（Cmd-Q，然后重新启动——仅关闭窗口是不够的）。其他客户端（Cursor、Claude Code）、手动连接和开发流程：[docs/mcp-setup.md](docs/mcp-setup.md)。 **3 · 让 LLM 初始化你的账号**——例如输入：“查看我的 Google 设置”。它会读取设置状态（工具 `setup_status`），向你展示缺失的内容，并为每个步骤提供**确切的命令**——但执行权在你手中。每个已连接的账号都会成为一个 **profile**，使用你指定的**别名**作为标识： ``` gwsa add perso # « perso » = ton alias · navigateur → choisir le compte → accepter gwsa add assoc # répéter pour chaque compte · gwsa list pour voir l'état ``` ## 工作原理 **LLM 永远无法扩大自身的访问权限。** 每一扇门——profile 锁、Drive 写入区域、新账号、IAM 角色——都必须通过人类操作开启，LLM 知道如何妥善地*请求*（启发式 elicitation）这些权限，但永远无法自行执行。 四个工作流程，其源码及说明均记录在 [diagrams/](diagrams/) 中： - **[初始设置](diagrams/onboarding-setup-initial/)**——上述 3 个步骤及其余引导流程。 - **[读取数据](diagrams/lecture-donnees-elicitee/)**——锁 → 启发式解锁 → 在策略下读取。 - **[连接账号](diagrams/onboarding-add-account-elicite/)**——双重物理屏障（Touch ID + OAuth 同意）。 - **[修复 IAM 偏差](diagrams/onboarding-reparation-iam/)**——通过两种路径进行检测（LLM 遇到 `403`，或通过 `provision-gcp.sh status` 检查），并由人类进行幂等修复。 ``` flowchart TD USER["Humain — unlock / grant / policy"] LLM["Clients LLM — Desktop / Cursor / Code"] MCP["bin/google-mcp — MCP stdio"] GW["gateway/ — policy + verrous, broker-ready"] ADMIN["admin web — 127.0.0.1:4877"] GWSA["bin/gwsa — profils · verrous · grants"] GWS["gws — CLI Google Workspace"] GOOGLE["APIs Google"] USER --> ADMIN --> GWSA USER --> GWSA LLM --> MCP --> GW --> GWSA --> GWS --> GOOGLE ``` *为什么需要 wrapper？* `gws` 一次只能管理一个账号（原生的多账号支持已被移除，[issue #293](https://github.com/googleworkspace/cli/issues/293))；`gwsa` / gateway 通过 `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` 隔离每个账号。本地 broker ([`bin/google-broker`](bin/google-broker)) 是唯一为 MCP 执行 `gws` 以访问**数据**的进程。参考：[docs/architecture.md](docs/architecture.md)。 ## 使用方式 - **通过 LLM**——按功能分组的 MCP 工具（发现、Gmail、Drive、启发式请求、诊断）：[docs/mcp-setup.md](docs/mcp-setup.md)。在 Claude Code 中，你可以用自然语言提问（“列出我个人账号中最近的 5 封邮件”）。 - **通过命令行和 Web 管理后台**（`gwsa`、锁、`gwsa admin`、Touch ID）：[docs/usage.md](docs/usage.md)。 - **策略模型**（每个服务默认拒绝，Drive 区域限制，授权许可）：[docs/policies.md](docs/policies.md)。 ## 安全性 核心理念：**默认不信任 LLM**。它可以*请求*权限（启发式请求）；但只有人类才能开启权限。具体而言： - **默认拒绝**——未在某个 profile 策略中明确声明的任何服务都将被拒绝；新账号默认采用谨慎的安全策略。 - **禁止发送邮件**——MCP 工具仅支持创建 Gmail 草稿。 - **Drive 写入区域限制**——仅限在授权的目录中写入，默认为临时目录。 - **基于 profile 的锁**——被锁定的 profile 将拒绝一切数据访问（包括 MCP），直到人类通过解锁操作（可选通过 **Touch ID**）解除限制。 - **Token 加密**——磁盘上采用 AES-256-GCM 加密，主密钥存储在 macOS Trousseau 中；仓库中不含任何敏感信息。 - **审计日志**——每次调用及其发起客户端均会被追踪记录。 更多细节——各阶段的保障、目前**尚不**保证的功能，以及如何报告安全漏洞：[SECURITY.md](SECURITY.md) · [docs/threat-model.md](docs/threat-model.md)。 ## 已知限制 - **OAuth 应用“未经验证”**：首次连接每个账号时，Google 会发出警告（*高级设置* → *继续访问...*）。这对于个人应用是正常现象。 - **测试模式 = Token 有效期 7 天**：将应用发布到 *生产环境* ([setup-oauth.md](docs/setup-oauth.md) 第 5 步) 可使 Token 持久有效。 - 免费的 API 配额对个人使用来说绰绰有余。成本：0 €。 ## 测试 - **自动化测试**：`./scripts/test.sh`——完全隔离的测试套件（策略、wrapper、gateway、broker）；不涉及真实账号，不依赖网络。 - **手动测试**：[tests/manuels/](tests/manuels/)——由 LLM 在真实账号上引导执行；只需输入“lance le test manuel drive-2-comptes”（前提：在相关 Drive 的根目录下准备一个名为 `ZZ-TESTS` 的沙盒测试文件夹）。 ## 版本控制 **Git tag** 是版本的真实来源。服务器会在 MCP 握手期间公布其版本：如果是从安装的副本运行，则为带 tag 的版本；如果是从 Clone 运行，则为 `dev`。 | 命令 | 功能描述 | |---|---| | `gwsa update` | 安装最新发布版本并切换至该版本 | | `gwsa update --check` | 显示已安装 / 可用版本，不进行任何写入操作 | | `gwsa update --to v0.1.0` | 回退至特定版本 | | `gwsa release` | 执行发布：根据提交推断 semver，生成 CHANGELOG，打 tag 并 push | | `gwsa release --print` | 预览将要发布的版本，不进行写入操作 | `gwsa release` 会根据自上一个 tag 以来的 [conventional commits](https://www.conventionalcommits.org/) 推断版本级别——`feat` → minor，`BREAKING CHANGE` → major，否则为 patch——并且在状态不明时拒绝发布：例如代码树不干净、不在 `main` 分支、落后于 `origin`、tag 已存在、没有需要发布的内容或测试未通过。 这些与 `./scripts/update.sh` 和 `./scripts/release.sh` 是相同的命令——`gwsa` 只是简单地将任务交接给它们，而 `gwsa help` 始终是所有可用命令的索引。 `gwsa update` 还会将你 PATH 中的 `gwsa` 指向已安装的副本，确保命令行环境与服务器版本一致。快速开始中的链接仅仅是一个引导。它绝不会触碰真实的文件，也不会修改目标不属于本项目的链接。 版本历史：[CHANGELOG.md](CHANGELOG.md)。开发轨道详情（同时连接多个版本、在不破坏现行版本的情况下进行开发）：[docs/mcp-setup.md](docs/mcp-setup.md)。 ## 维护 - `./scripts/sync-skills.sh`——在更新 gws 后重新同步官方 skills。 - 如果 gws 中恢复了原生的多账号支持 (`--account`) ([issue #293](https://github.com/googleworkspace/cli/issues/293))，该 wrapper 将退化为一个简单的别名。 ## 支持本项目 本项目利用业余时间开发，采用 [MIT](LICENSE) 许可证。如果它对你有帮助，欢迎[请我喝杯咖啡 ☕](https://buymeacoffee.com/elzinko)。

标签：DLL 劫持, Google Workspace, MCP, OAuth, 人工智能集成, 大语言模型, 本地化部署