Quickstart · How it works · Security · Docs
Multi-account Google Workspace for LLM agents — 100 % local. Connect Claude Desktop, Claude Code or Cursor to several Google accounts through a local MCP server. The agent can ask for access; only you grant it — every unlock, Drive grant and new account stays a human gesture.
✨ What you get
- Multi-account, not one token — each account is a profile with its own policy, locks and Drive zones. The agent targets an alias, never “your Google” as a whole.
- The human holds every door — unlock, Drive grant, new account, IAM fix: the agent proposes the exact command (elicitation), you run it.
- Default-deny by design — any undeclared service is refused; Gmail tools stop at the draft (no sending); Drive writes stay inside granted folders.
- 100 % local — encrypted tokens (AES-256-GCM, master key in the macOS Keychain), per-client audit log. The only cloud step is a one-shot OAuth credential.
- Scope today — Gmail + Drive through MCP; Calendar next. Docs, Sheets and Tasks are reachable through the
mag CLI.
🚀 Quickstart
macOS Apple Silicon.
Prerequisite — the upstream gws CLI (the Google Workspace CLI this project wraps) and Python 3:
brew install googleworkspace-cli
1. Install — no clone needed:
curl -fsSL https://raw.githubusercontent.com/elzinko/google-mcp-multi-account/main/install.sh | bash
This puts the latest release on your machine and mag on your PATH. By default it wires no client — it prints the command to connect each one (mag wire desktop / mag wire code, Cursor manual); pass --wire to connect them during install.
2. Google setup (~10 min, once) — an OAuth project in Google Cloud: docs/setup-oauth.md. No account connects and no Google data flows until it's done — setup_status still runs to guide you.
3. Connect an account, then restart Claude Desktop (Cmd-Q):
mag add perso [email protected] # "perso" = short name · the email pins the account
mag list # profiles + state
Ask the agent: “give me a rundown of my Google setup” — it reads the state and proposes the exact command for each missing step; you run them. Update later, still clone-free: mag update. Full detail: docs/mcp-setup.md · docs/setup-oauth.md.
🧭 How it works
The LLM can never widen its own access. Every door opens by a human gesture the agent can request but not perform.
flowchart LR
USER["🧑 Human"]
LLM["LLM clients — Desktop / Code / Cursor"]
MCP["bin/google-mcp — MCP stdio"]
GW["gateway/ — enforces policy + locks"]
STATE["locks · grants · policy"]
GWSA["bin/mag"]
GOOGLE["Google APIs"]
LLM --> MCP --> GW --> GOOGLE
GW -.->|reads| STATE
USER -->|unlock / grant / policy| GWSA -->|writes| STATE
Why a wrapper, the local broker, who talks to whom: docs/architecture.md. Step-by-step walkthroughs: diagrams/.
👥 Usage by persona
- Daily user (agent operator) — you chat with the agent in Claude Desktop, Code or Cursor. It reads your setup and proposes the exact
mag command for anything it can't do itself — unlock a profile, grant a Drive folder, connect an account — and you run it. Nothing is sent or widened without your gesture. Start at Quickstart.
- Admin / owner — you decide what each account may do. Per-profile policy (default-deny), locks with optional Touch ID, temporary Drive zones, and per-conversation session rights — all from the local web admin (
mag admin → http://127.0.0.1:4877) or the mag CLI. See docs/admin.md and docs/policies.md.
- Contributor — you build against the local backlog under
features/, run the hermetic tests, and open one PR per feature. See Contributing.
🔒 Security
Stance: don’t trust the LLM by default — it can ask, only a human opens. Per-profile locks (optional Touch ID), zoned Drive writes, no mail sending, encrypted tokens. Guarantees phase by phase, what is not yet covered, and how to report a flaw: SECURITY.md · docs/threat-model.md. Honest self-critique (strengths, limits, competition): docs/critique.md.
🛠 Development
./scripts/test.sh # hermetic suite (policy, wrapper, gateway, broker) — no real account, no network
Project structure
bin/ # google-mcp (MCP server) · mag (CLI wrapper) · google-broker
gateway/ # policy, locks, MCP server, signed elicitation
scripts/ # provision-gcp · update · release · test
docs/ # setup, usage, policies, architecture, security, critique
site/ # product landing + docs hub (English, FR/EN toggle)
features/ # backlog — one card per feature/bug
Product / MCP server google-multi-account (source of truth: gateway/config.py PRODUCT_SLUG) · git repo google-mcp-multi-account · CLI mag (this project's wrapper — what you run; formerly gwsa/gma, still deprecated aliases) · MCP binary google-mcp · upstream dependency gws = the Google Workspace CLI that mag wraps (install it first).
🤝 Contributing
- Dev setup — clone, then run the hermetic suite (no real account, no network —
gws and the network are stubbed):
git clone https://github.com/elzinko/google-mcp-multi-account && cd google-mcp-multi-account
./scripts/test.sh
Running the tool against real accounts also needs the gws CLI (brew install googleworkspace-cli) — see Quickstart.
- Backlog-driven — work is one Markdown card per feature/bug under
features/ (priority-sorted index: features/BACKLOG.md). Pick a ready card; one feature = one branch = one PR.
- Commit conventions — Conventional Commits (
feat:, fix:, docs:, refactor:…); mag release derives the semver tag from them.
- Before a PR —
./scripts/test.sh green, and walk the reviewer checklist in docs/PR_VALIDATION.md. Every PR gets an adversarial review before merge.
📚 Further reading
License
MIT — built in spare time. If it helps you, buy me a coffee ☕.
