mcp-google-multi 4.5.0-alpha.3 → 5.0.0-beta.1

package/README.md

@@ -1,470 +1,129 @@
 # mcp-google-multi
 
-A local [MCP](https://modelcontextprotocol.io) server that gives Claude Code (and any MCP client) access to **Gmail**, **Google Drive**, **Google Calendar**, **Google Sheets**, **Google Docs**, **Google Contacts**, **Google Search Console**, **Google Tasks**, **Google Meet**, and optionally **Google Forms**, **Google Chat**, and **Google Workspace Admin** APIs across multiple Google accounts simultaneously.
+A **local** [MCP](https://modelcontextprotocol.io) server that gives Claude Code (and any MCP client) access to your **Google Workspace** — Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console (plus optional Forms, Chat, and Workspace Admin) — across **multiple Google accounts** at once.
 
 [![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
 
-## Features
-
-- **Multi-account** — manage any number of Google accounts from a single server
-- **175 tools** across 13 Google services
-- **Tiered OAuth scopes** — base scopes always granted; Forms/Chat/Alert Center are opt-in bundles; Admin scopes are per-account opt-in with a separate safety flag for destructive writes
-- **Config-driven accounts** — defined in `.env`, no code changes needed
-- **Auto-refresh** — OAuth tokens refresh transparently and persist to disk
-- **Stdio transport** — runs as a local subprocess, no hosting needed
-
-## Tools
-
-### Gmail (21 tools)
-
-| Tool | Description |
-|------|-------------|
-| `gmail_search` | Search messages with Gmail query syntax |
-| `gmail_read` | Read a full message by ID |
-| `gmail_read_thread` | Read all messages in a thread |
-| `gmail_send` | Send an email (optional `htmlBody` for multipart/alternative) |
-| `gmail_download_attachment` | Download an email attachment to local disk |
-| `gmail_create_draft` | Create a draft (optional `htmlBody` for multipart/alternative) |
-| `gmail_modify_labels` | Add/remove labels on a message (star, archive, mark read, etc.) |
-| `gmail_trash` | Move a message to Trash (recoverable) |
-| `gmail_delete` | Permanently delete a message (irreversible) |
-| `gmail_batch_modify` | Bulk add/remove labels across up to 1000 messages |
-| `gmail_batch_delete` | Permanently delete multiple messages (irreversible) |
-| `gmail_list_drafts` | List all drafts |
-| `gmail_get_draft` | Read a specific draft |
-| `gmail_send_draft` | Send an existing draft |
-| `gmail_list_labels` | List all labels (system + custom) |
-| `gmail_create_label` | Create a custom label |
-| `gmail_delete_label` | Delete a label |
-| `gmail_get_profile` | Get account email, message count, history ID |
-| `gmail_list_history` | Get mailbox changes since a history ID |
-| `gmail_get_vacation` | Read vacation responder settings |
-| `gmail_set_vacation` | Enable/disable vacation responder |
-
-### Google Drive (35 tools)
-
-| Tool | Description |
-|------|-------------|
-| `drive_search` | Search files with Drive query syntax (shared drives included) |
-| `drive_read` | Read file content (exports Workspace docs as text) |
-| `drive_list` | List files in a folder or root |
-| `drive_upload` | Upload a local file to Drive (optional `convertTo` imports it as a native Google Doc/Sheet/Slides) |
-| `drive_download` | Download a binary file to local disk |
-| `drive_export` | Export Google Docs/Sheets/Slides to PDF, DOCX, XLSX, Markdown, etc. |
-| `drive_create_folder` | Create a new folder |
-| `drive_update` | Rename, move, or replace file content |
-| `drive_delete` | Permanently delete a file (irreversible) |
-| `drive_trash` | Move a file to trash (recoverable) |
-| `drive_untrash` | Restore a trashed file |
-| `drive_empty_trash` | Permanently delete every file in trash |
-| `drive_copy` | Duplicate a file |
-| `drive_move` | Move a file between folders |
-| `drive_share` | Share with user/group/domain/anyone (with `transferOwnership` + `expirationTime`) |
-| `drive_list_permissions` | List who has access to a file |
-| `drive_permission_update` | Change a permission's role / expiration in place |
-| `drive_remove_permission` | Revoke access |
-| `drive_comment_create` / `_list` / `_get` / `_update` / `_delete` | Full comment CRUD with anchor support |
-| `drive_reply_create` / `_list` / `_update` / `_delete` | Reply CRUD; reply.create accepts `action: resolve | reopen` |
-| `drive_revision_list` / `_update` / `_delete` | Version history; `keepForever` pins against the 200-version cap |
-| `drive_access_proposal_list` / `_resolve` | Triage "Request access" submissions |
-| `drive_shared_drives_list` / `drive_shared_drive_get` | Shared drive discovery |
-| `drive_get_about` | Storage quota and account info |
-
-### Google Calendar (11 tools)
-
-| Tool | Description |
-|------|-------------|
-| `calendar_list_calendars` | List all calendars |
-| `calendar_list_events` | List/search events with time range |
-| `calendar_get_event` | Get a single event by ID |
-| `calendar_create_event` | Create an event |
-| `calendar_update_event` | Update an event |
-| `calendar_delete_event` | Delete an event |
-| `calendar_quick_add` | Create event from natural language (e.g. "Lunch Thursday 1pm") |
-| `calendar_move_event` | Move an event between calendars |
-| `calendar_list_instances` | List occurrences of a recurring event |
-| `calendar_get_freebusy` | Check free/busy times for calendars |
-| `calendar_create_calendar` | Create a new calendar |
-
-### Google Sheets (29 tools)
-
-| Tool | Description |
-|------|-------------|
-| `sheets_create` | Create a new spreadsheet |
-| `sheets_get` | Get spreadsheet metadata |
-| `sheets_read_range` / `sheets_batch_read` | Read values |
-| `sheets_write_range` / `sheets_batch_write` | Write values |
-| `sheets_append_rows` | Append after existing data |
-| `sheets_clear_range` / `sheets_batch_clear` | Clear values (preserves formatting) |
-| `sheets_add_sheet` / `sheets_delete_sheet` / `sheets_duplicate_sheet` | Tab management |
-| `sheets_update_sheet_properties` | Rename, freeze, color, hide, resize |
-| `sheets_format_cells` | Colors, fonts, alignment, number formats |
-| `sheets_update_borders` | Cell borders with style + color |
-| `sheets_merge_cells` / `sheets_unmerge_cells` | Cell merging |
-| `sheets_add_conditional_format_rule` | Boolean and gradient conditional formatting |
-| `sheets_sort_range` | Multi-column sort |
-| `sheets_set_basic_filter` / `sheets_clear_basic_filter` | Filter rows |
-| `sheets_find_replace` | Regex-capable, scope-aware find/replace |
-| `sheets_auto_resize_dimensions` | Fit rows/columns to content |
-| `sheets_set_data_validation` | Dropdowns, checkboxes, custom rules |
-| `sheets_add_named_range` / `sheets_delete_named_range` | Named ranges |
-| `sheets_insert_dimension` / `sheets_delete_dimension` | Insert/delete rows or columns |
-| `sheets_batch_update` | Generic batchUpdate escape hatch (any Request type) |
-
-### Google Docs (27 tools)
-
-| Tool | Description |
-|------|-------------|
-| `docs_create` | Create a new document |
-| `docs_get` | Metadata + optional tab content / suggestionsViewMode |
-| `docs_read` | Read document content as plain text |
-| `docs_insert_text` | Insert text at position or end |
-| `docs_replace_text` | Find and replace |
-| `docs_delete_range` | Delete a character range |
-| `docs_update_style` | Inline text formatting (bold, italic, font, size) |
-| `docs_update_paragraph_style` | Alignment, heading, indents, spacing |
-| `docs_update_document_style` | Page size, margins, header/footer behavior |
-| `docs_insert_table` | Insert a table |
-| `docs_modify_table` | insertRow / insertColumn / deleteRow / deleteColumn / mergeCells / unmergeCells |
-| `docs_create_named_range` / `docs_delete_named_range` / `docs_replace_named_range_content` | Mail-merge primitive |
-| `docs_create_paragraph_bullets` / `docs_delete_paragraph_bullets` | Bulleted/numbered lists |
-| `docs_insert_inline_image` | PNG/JPEG/GIF image insertion |
-| `docs_insert_page_break` / `docs_insert_section_break` | Layout breaks |
-| `docs_create_header` / `docs_delete_header` / `docs_create_footer` / `docs_delete_footer` | Branded headers and footers |
-| `docs_add_tab` / `docs_delete_tab` / `docs_update_tab_properties` | Tabs CRUD |
-| `docs_batch_update` | Generic batchUpdate escape hatch (any Request type) |
-
-### Google Contacts (9 tools)
-
-| Tool | Description |
-|------|-------------|
-| `contacts_search` | Search contacts |
-| `contacts_get` | Get one contact |
-| `contacts_list` | List contacts (paginated) |
-| `contacts_create` | Create a contact |
-| `contacts_update` | Update a contact |
-| `contacts_delete` | Delete a contact |
-| `contacts_groups_list` | List groups |
-| `contacts_group_members` | List members of a group |
-| `contacts_group_create` | Create a group |
-
-### Google Search Console (10 tools)
-
-| Tool | Description |
-|------|-------------|
-| `searchconsole_sites_list` | List Search Console properties |
-| `searchconsole_sites_get` | Get a property |
-| `searchconsole_sites_add` | Add a property |
-| `searchconsole_sites_delete` | Remove a property |
-| `searchconsole_sitemaps_list` | List sitemaps |
-| `searchconsole_sitemaps_get` | Sitemap status |
-| `searchconsole_sitemaps_submit` | Submit a sitemap |
-| `searchconsole_sitemaps_delete` | Delete a sitemap |
-| `searchconsole_searchanalytics_query` | Query search analytics |
-| `searchconsole_url_inspect` | Inspect a URL |
-
-### Google Tasks (12 tools) — _new in v4_
-
-| Tool | Description |
-|------|-------------|
-| `tasks_lists_list` / `tasks_list_get` / `tasks_list_insert` / `tasks_list_update` / `tasks_list_delete` | Tasklist management |
-| `tasks_list` | List tasks (filter by completion, due, updated time) |
-| `tasks_get` / `tasks_insert` / `tasks_update` / `tasks_delete` | Task CRUD |
-| `tasks_move` | Re-parent / re-position / move to another list |
-| `tasks_clear` | Delete every completed task |
-
-### Google Meet (5 tools) — _new in v4_
-
-| Tool | Description |
-|------|-------------|
-| `meet_conference_records_list` | List past Meet sessions |
-| `meet_conference_record_get` | Get one record |
-| `meet_recordings_list` | Recordings on a record |
-| `meet_transcripts_list` | Transcripts on a record |
-| `meet_transcript_entries_list` | Per-speaker transcript text |
-
-### Google Forms (4 tools, optional bundle) — _new in v4_
-
-Enable with `GOOGLE_OPTIONAL_SCOPES=forms` in `.env`.
-
-| Tool | Description |
-|------|-------------|
-| `forms_get` | Form definition |
-| `forms_responses_list` | List responses with filter |
-| `forms_response_get` | Single response |
-| `forms_watches_list` | List Pub/Sub watches |
-
-### Google Chat (4 tools, optional bundle) — _new in v4_
-
-Enable with `GOOGLE_OPTIONAL_SCOPES=chat` in `.env` (combine: `GOOGLE_OPTIONAL_SCOPES=forms,chat`).
-
-| Tool | Description |
-|------|-------------|
-| `chat_spaces_list` | Spaces the user is in |
-| `chat_spaces_get` | One space |
-| `chat_messages_create` | Send text or Card v2 |
-| `chat_messages_list` | List messages with filter / orderBy |
-
-### Google Workspace Admin (6 tools, admin bundle) — _new in v4_
-
-Enable per-account with `GOOGLE_ADMIN_ACCOUNTS=alias1,alias2` in `.env`. Requires the account to be a Workspace super-admin. Personal `@gmail.com` accounts will 403 — never list them here. Destructive writes additionally require `GOOGLE_ALLOW_ADMIN_WRITES=true`.
-
-| Tool | Description |
-|------|-------------|
-| `reports_activities_list` | Workspace audit log (login, drive, gmail, admin, token, etc.) |
-| `admin_users_list` / `admin_users_get` | User directory reads |
-| `admin_users_update` | User edits (gated, see env flag above) |
-| `admin_groups_list` / `admin_group_members_list` | Group + member reads |
-
-Every tool accepts an `account` parameter matching one of your configured aliases.
-
-### Google Alert Center (2 tools, optional bundle) — _new in v4_
-
-Enable with `GOOGLE_OPTIONAL_SCOPES=alertcenter` in `.env`.
-
-| Tool | Description |
-|------|-------------|
-| `alertcenter_alerts_list` / `alertcenter_alert_get` | Security alerts (suspicious login, phishing, leaked password, Drive exfil) |
-
-> **⚠ Requires service-account domain-wide delegation.** Unlike every other bundle, the Alert Center `apps.alerts` scope **cannot** be granted through this server's interactive user-consent OAuth flow — Google rejects it with `Error 400: invalid_scope` / "Some requested scopes cannot be shown". Per [Google's docs](https://developers.google.com/workspace/admin/alertcenter/guides/auth), Alert Center requires a service account with domain-wide delegation. This server is user-OAuth only, so enabling this bundle declares the scope and registers the tools, but the API will reject the resulting tokens until service-account auth is added (see [#4](https://github.com/bakissation/mcp-google-multi/issues/4)). The bundle is kept separate precisely so this limitation never blocks the working admin tools above.
-
-## Prerequisites
-
-- Node.js 18+
-- A Google Cloud project with the relevant APIs enabled (see step 1 below)
-- An OAuth 2.0 Client ID (Desktop app type)
+> Open-source and **funded by [IdeaCrafters](https://github.com/IdeaCraftersHQ)** — the studio that pays for its development and upkeep.
 
-## Setup
+- 🔑 **Multi-account** — drive any number of your Google accounts from one server, each by a short alias.
+- 🔒 **Secure by default** — refresh tokens **encrypted at rest** (AES-256-GCM); **writes are deny-by-default**; no telemetry — it talks only to Google.
+- 📦 **npm-first** — install and run with `npx`; everything configured through env vars.
+- 🧰 **~170 tools** across 12 services → full list in **[COVERAGE.md](./COVERAGE.md)**.
 
-### 1. Google Cloud Credentials
-
-1. Go to [Google Cloud Console](https://console.cloud.google.com).
-2. Create or select a project.
-3. Enable the APIs you intend to use:
-   - **Always required:** [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com), [Google Drive API](https://console.cloud.google.com/apis/library/drive.googleapis.com), [Google Calendar API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com), [Google Sheets API](https://console.cloud.google.com/apis/library/sheets.googleapis.com), [Google Docs API](https://console.cloud.google.com/apis/library/docs.googleapis.com), [People API](https://console.cloud.google.com/apis/library/people.googleapis.com), [Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com), [Google Tasks API](https://console.cloud.google.com/apis/library/tasks.googleapis.com), [Google Meet API](https://console.cloud.google.com/apis/library/meet.googleapis.com).
-   - **Optional bundles (only if you enable them):** [Google Forms API](https://console.cloud.google.com/apis/library/forms.googleapis.com), [Google Chat API](https://console.cloud.google.com/apis/library/chat.googleapis.com), [Alert Center API](https://console.cloud.google.com/apis/library/alertcenter.googleapis.com) (the `alertcenter` bundle also needs service-account domain-wide delegation — see the Alert Center section above).
-   - **Admin bundle (only if you set `GOOGLE_ADMIN_ACCOUNTS`):** [Admin SDK API](https://console.cloud.google.com/apis/library/admin.googleapis.com).
-4. Go to **APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID**.
-5. Application type: **Desktop app**.
-6. Add authorized redirect URI: `http://localhost:4242/oauth2callback`.
-7. Copy the **Client ID** and **Client Secret**.
+> v5 is **local + user-OAuth only**. Service accounts and hosting (and the APIs they unlock) are on the [roadmap](https://github.com/bakissation/mcp-google-multi/milestones). **Upgrading from v4?** Jump to [Upgrading](#upgrading-from-v4).
 
-### 2. Install & Configure
+## Quick start
 
-**Option A — from npm (no clone):**
+You need **Node 20+**, a Google Cloud OAuth client (~2 min — [setup below](#google-cloud-setup)), and a random 32-byte key.
 
 ```bash
-npm install -g mcp-google-multi    # installs the `mcp-google-multi` CLI
-# …or run on demand without installing: npx mcp-google-multi
-```
-
-Published with channel dist-tags — `@latest` (stable), `@dev` (alpha), `@staging` (beta); e.g. `npm i -g mcp-google-multi@dev` for the latest alpha.
-
-**Option B — from source:**
-
-```bash
-git clone https://github.com/bakissation/mcp-google-multi.git
-cd mcp-google-multi
-npm install && npm run build
-cp .env.example .env
-```
-
-Create a `.env` (from source, `.env.example` is the template; from npm, make one in the directory you'll run the server from) with:
+# 1) install
+npm i -g mcp-google-multi
 
-```env
-GOOGLE_CLIENT_ID=your_client_id_here
-GOOGLE_CLIENT_SECRET=your_client_secret_here
+# 2) put your config + creds in the environment (see "Configuration").
+#    Easiest for a quick try — export them, or drop a .env in your working dir:
+#    GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_ACCOUNTS, MASTER_KEY, GOOGLE_PROFILE
 
-# Define your accounts as alias:email pairs (comma-separated)
-GOOGLE_ACCOUNTS=work:you@company.com,personal:you@gmail.com
+# 3) authenticate each account (opens a browser; one-time per account)
+mcp-google-multi auth --account work
+mcp-google-multi auth --account personal
 
-# Optional (v4): enable Forms, Chat, and/or Alert Center tool bundles
-# (alertcenter additionally requires service-account domain-wide delegation)
-# GOOGLE_OPTIONAL_SCOPES=forms,chat
-
-# Optional (v4): grant Workspace admin scopes to specific accounts
-# GOOGLE_ADMIN_ACCOUNTS=work
-
-# Optional (v4): unlock destructive admin writes (admin_users_update)
-# GOOGLE_ALLOW_ADMIN_WRITES=true
+# 4) register with Claude Code
+claude mcp add google-multi -s user -- npx -y mcp-google-multi
 ```
 
-### 3. Build
+Restart your MCP client and the tools appear. Tokens are written **encrypted** to `~/.config/mcp-google-multi/tokens/` (override with `TOKEN_STORE_PATH`) — useless to anyone without your `MASTER_KEY`.
 
-```bash
-npm run build
-```
-
-### 4. Authenticate Accounts
-
-```bash
-npm run auth -- work       # opens browser → log in with you@company.com
-npm run auth -- personal   # opens browser → log in with you@gmail.com
-```
+Generate a key: `openssl rand -base64 32`.
 
-Each saves a token to `tokens/<alias>/token.json`. Tokens auto-refresh — you should only need to do this once per account.
+## Recommended: keep secrets in a vault (Infisical)
 
-### 5. Register in Claude Code
+A plaintext `.env` is fine to try it out, but for a daily driver, **don't leave `GOOGLE_CLIENT_SECRET` + `MASTER_KEY` on disk** — inject them at launch from a secrets manager. The server just reads `process.env` (it has no idea where the values come from), so wrap it with [Infisical](https://infisical.com):
 
 ```bash
-claude mcp add google-multi -s user -- node /absolute/path/to/mcp-google-multi/dist/index.js
-```
-
-Or add it manually to your Claude Code MCP config:
-
-```json
-{
-  "mcpServers": {
-    "google-multi": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-google-multi/dist/index.js"]
-    }
-  }
-}
+#!/usr/bin/env bash
+# ~/.local/bin/mcp-google-multi-run  — chmod +x, then register this as the MCP command
+set -euo pipefail
+export INFISICAL_TOKEN="$(infisical login --method=universal-auth \
+  --client-id "$YOUR_CLIENT_ID" --client-secret "$YOUR_CLIENT_SECRET" --plain --silent)"
+exec infisical run --projectId <project> --env prod --path /mcp-google-multi \
+  -- npx -y mcp-google-multi
 ```
 
-If you installed from npm, point at the package instead and pass config via `env` (authenticate first with `mcp-google-multi auth --account <alias>`):
-
-```json
-{
-  "mcpServers": {
-    "google-multi": {
-      "command": "npx",
-      "args": ["-y", "mcp-google-multi"],
-      "env": {
-        "GOOGLE_CLIENT_ID": "your_client_id_here",
-        "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
-        "GOOGLE_ACCOUNTS": "work:you@company.com,personal:you@gmail.com"
-      }
-    }
-  }
-}
-```
-
-## Migrating from v3
-
-v4.0.0 grows the base OAuth scope set (Tasks and Meet are now included by default). Existing v3 tokens lack those scopes and the corresponding tools will 403.
-
-1. `git pull && npm install && npm run build`.
-2. Re-authenticate every account: `npm run auth -- <alias>` for each alias.
-3. If you want Forms or Chat tools: set `GOOGLE_OPTIONAL_SCOPES=forms,chat` in `.env` **before** re-authing.
-4. If you're a Workspace admin: list relevant accounts in `GOOGLE_ADMIN_ACCOUNTS` **before** re-authing those accounts. Set `GOOGLE_ALLOW_ADMIN_WRITES=true` only if you need destructive admin operations.
-5. In Google Cloud Console, enable any new APIs you'll use (Tasks, Meet, Forms, Chat, Admin SDK, Alert Center).
-
-## Adding / Removing Accounts
-
-Edit the `GOOGLE_ACCOUNTS` variable in `.env`, rebuild, and authenticate the new account:
-
 ```bash
-# Add a new account
-# .env: GOOGLE_ACCOUNTS=work:you@company.com,personal:you@gmail.com,freelance:you@freelance.com
-
-npm run build
-npm run auth -- freelance
+claude mcp add google-multi -s user -- ~/.local/bin/mcp-google-multi-run
 ```
 
-No code changes required.
+Now the only thing on disk is the **encrypted** token store. Pass the token via the `INFISICAL_TOKEN` env var (as above), **not** a `--token` flag, so it never shows up in `ps`. (Any secrets manager works — Doppler, Vault, 1Password CLI, etc. — the pattern is the same.)
 
-## OAuth Scopes
+## Configuration
 
-### Base (always granted)
+| Env var | Required | Description |
+|---|---|---|
+| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | ✓ | OAuth **Desktop** client from Google Cloud |
+| `GOOGLE_ACCOUNTS` | ✓ | `alias:email,…` — e.g. `work:you@co.com,personal:you@gmail.com` |
+| `MASTER_KEY` | ✓ | base64 32-byte key that encrypts the token store (`openssl rand -base64 32`) |
+| `GOOGLE_PROFILE` | — | write policy: `read-only` (default) · `safe-writes` · `full-writes` |
+| `GOOGLE_READ_ONLY` | — | `true` = hard kill-switch for all writes |
+| `GOOGLE_WRITE_ALLOW` / `GOOGLE_WRITE_DENY` | — | glob overrides, e.g. `calendar:*`, `*:delete*` |
+| `GOOGLE_OPTIONAL_SCOPES` | — | extra bundles: `forms`, `chat` |
+| `GOOGLE_ADMIN_ACCOUNTS` | — | aliases granted Workspace-admin scopes (the account's own super-admin OAuth) |
+| `TOKEN_STORE_PATH` | — | override the encrypted token dir (default: `~/.config/mcp-google-multi/tokens`) |
 
-| Scope | Access |
-|-------|--------|
-| `gmail.modify` | Read, label, trash, delete emails |
-| `gmail.send` | Send emails |
-| `drive` | Full Drive access (read, upload, share, comments, etc.) |
-| `calendar` | Full calendar access |
-| `spreadsheets` | Read/write Google Sheets |
-| `documents` | Read/write Google Docs |
-| `contacts` | Read/write Google Contacts |
-| `webmasters` | Google Search Console |
-| `tasks` | Read/write Google Tasks |
-| `meetings.space.readonly` | Read past Meet conference records and transcripts |
+Inspect the resolved setup any time: `mcp-google-multi config check`.
 
-### Optional (per-`GOOGLE_OPTIONAL_SCOPES` env var)
+## Write-control (deny-by-default)
 
-| Bundle key | Scopes |
-|------------|--------|
-| `forms` | `forms.body`, `forms.responses.readonly` |
-| `chat` | `chat.spaces`, `chat.messages`, `chat.messages.create` |
-| `alertcenter` | `apps.alerts` — ⚠ requires service-account domain-wide delegation; not grantable via user OAuth (see Alert Center section) |
+Reads are never gated. **Every create/update/delete is off until you opt in** — pick a profile:
 
-### Admin (per-`GOOGLE_ADMIN_ACCOUNTS` env var)
+| `GOOGLE_PROFILE` | Allows |
+|---|---|
+| `read-only` (default) | reads only |
+| `safe-writes` | create + update (deletes still blocked) |
+| `full-writes` | everything |
 
-Only granted to accounts explicitly listed. Personal Gmail accounts will 403 on these scopes — never list them.
+`GOOGLE_READ_ONLY=true` overrides all. For fine control: `GOOGLE_WRITE_ALLOW="calendar:*, sheets:update*"` and `GOOGLE_WRITE_DENY="*:delete*"` (deny wins). `mcp-google-multi config check` prints the resolved policy and exactly which tools are enabled.
 
-| Scope | Access |
-|-------|--------|
-| `admin.reports.audit.readonly` | Workspace audit log |
-| `admin.directory.user` | Read/write Workspace users (writes also gated by `GOOGLE_ALLOW_ADMIN_WRITES`) |
-| `admin.directory.group.readonly` | Read groups |
-| `admin.directory.group.member.readonly` | Read group members |
+## What's covered
 
-## Project Structure
+~170 tools across Gmail, Drive, Calendar, Sheets, Docs, Contacts, Search Console, Tasks, Meet, and (optional) Forms, Chat, Workspace Admin. **Full per-tool list → [COVERAGE.md](./COVERAGE.md).** Every tool takes an `account` argument matching one of your aliases.
 
-```
-mcp-google-multi/
-├── src/
-│   ├── index.ts          # Entry point: MCP server or auth CLI
-│   ├── accounts.ts       # Account config parser (reads from .env)
-│   ├── auth.ts           # Scope tier resolution + OAuth flow
-│   ├── client.ts         # OAuth2Client factory with auto-refresh
-│   ├── types.ts          # Shared TypeScript types
-│   └── tools/
-│       ├── _errors.ts          # Shared googleapis error → MCP response mapper
-│       ├── gmail.ts            # Gmail (21)
-│       ├── drive.ts            # Drive (35)
-│       ├── calendar.ts         # Calendar (11)
-│       ├── sheets.ts           # Sheets (29)
-│       ├── docs.ts             # Docs (27)
-│       ├── contacts.ts         # Contacts (9)
-│       ├── searchconsole.ts    # Search Console (10)
-│       ├── tasks.ts            # Tasks (12) — v4
-│       ├── meet.ts             # Meet (5) — v4
-│       ├── forms.ts            # Forms (4, optional) — v4
-│       ├── chat.ts             # Chat (4, optional) — v4
-│       └── admin.ts            # Admin SDK (6, admin) + Alert Center (2, alertcenter bundle) — v4
-├── tests/                # vitest unit tests (gmail-mime, path-safety, field-mask helpers)
-├── tokens/               # OAuth tokens per account (gitignored)
-├── dist/                 # Compiled output (gitignored)
-├── .env                  # Your credentials (gitignored)
-├── .env.example          # Template for .env
-├── CHANGELOG.md
-├── CLAUDE.md             # Conventions for AI assistants working on this codebase
-├── package.json
-├── tsconfig.json
-└── LICENSE
-```
+## Google Cloud setup
 
-## Troubleshooting
+1. [Google Cloud Console](https://console.cloud.google.com) → create or select a project.
+2. Enable the APIs you'll use: Gmail, Drive, Calendar, Sheets, Docs, People, Search Console, Tasks, Meet (+ Forms / Chat / Admin SDK if you enable those bundles).
+3. **APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app**.
+4. Add the redirect URI `http://localhost:4242/oauth2callback`.
+5. Copy the **Client ID** + **Client Secret** into your environment.
 
-**"GOOGLE_ACCOUNTS is not set"** — Make sure your `.env` file exists in the project root and has the `GOOGLE_ACCOUNTS` variable set.
+## Upgrading from v4
 
-**"No token file found for account X"** — Run `npm run auth -- <alias>` to authenticate that account.
+v5 is a breaking change, but the migration is a one-time, ~2-minute step:
 
-**"Port 4242 is already in use"** — Another process is using port 4242. Close it and retry the auth flow.
+1. Update: `npm i -g mcp-google-multi@latest` (or update your client config).
+2. Add **`MASTER_KEY`** to your environment (`openssl rand -base64 32`) — now required.
+3. Encrypt existing tokens: `mcp-google-multi migrate-tokens` (reads your old `tokens/<alias>/token.json` and encrypts them) — or just re-auth each account.
+4. Writes are now **deny-by-default** — set `GOOGLE_PROFILE=safe-writes` (or `full-writes`) to keep writing. (`GOOGLE_ALLOW_ADMIN_WRITES` is gone — replaced by write-control profiles.)
 
-**Token refresh errors** — Delete the token file at `tokens/<alias>/token.json` and re-authenticate.
+## Security
 
-**Tasks / Meet tools return 403 after upgrading from v3** — You haven't re-authed since the base scope set grew. Run `npm run auth -- <alias>` for every account.
+Your OAuth, your machine. Refresh tokens are **AES-256-GCM encrypted at rest** (decryptable only with your `MASTER_KEY`), writes are deny-by-default, and the server has **no telemetry** — it connects only to Google's APIs. Found a vulnerability? Report it privately — see [SECURITY.md](./SECURITY.md), never a public issue.
 
-**`forms_*` or `chat_*` tools missing from the tool list** — They're only registered when `GOOGLE_OPTIONAL_SCOPES` includes their bundle key. Set `GOOGLE_OPTIONAL_SCOPES=forms,chat` (or one of them) in `.env`, rebuild, and re-auth the accounts that need them.
+## Roadmap
 
-**Admin tools missing or returning 403** — Admin tools only register if `GOOGLE_ADMIN_ACCOUNTS` is set. The listed accounts must be Workspace super-admins, and you must re-auth them after adding the env var so the new scopes are granted. `admin_users_update` additionally requires `GOOGLE_ALLOW_ADMIN_WRITES=true`.
+Maintainer-led. Direction is tracked publicly as **[GitHub Milestones](https://github.com/bakissation/mcp-google-multi/milestones)** (discover-first tooling → exhaustive API coverage → service accounts + hosting in v6). Not accepting unsolicited feature PRs; bug reports are welcome.
 
 ## Contributing
 
-Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first. In short: **open pull requests against the `dev` branch** — changes are promoted `dev → staging → main`, and `main` is release-only. Run `typecheck`/`lint`/`test`/`build` before submitting, and use Conventional Commits.
-
-By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). For security issues, **do not open a public issue** — see [SECURITY.md](SECURITY.md).
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md). Security issues go to [SECURITY.md](./SECURITY.md), never a public issue.
 
-## Author
+## Credits
 
-**Abdelbaki Berkati** — [berkati.xyz](https://berkati.xyz) · [@bakissation](https://github.com/bakissation)
+Built and maintained by **Abdelbaki Berkati** — [berkati.xyz](https://berkati.xyz) · [@bakissation](https://github.com/bakissation). [Read the case study →](https://berkati.xyz/case-studies/mcp-google-multi/)
 
-[Read the case study →](https://berkati.xyz/case-studies/mcp-google-multi/)
+Development is **funded by [IdeaCrafters](https://ideacrafters.com)** ([@IdeaCraftersHQ](https://github.com/IdeaCraftersHQ)) — the studio that pays for this OSS to exist.
 
 ## License
 
-[MIT](LICENSE)
+[MIT](./LICENSE)

package/dist/accounts.js

@@ -1,11 +1,14 @@
 import dotenv from 'dotenv';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
+import { homedir } from 'node:os';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config();
 dotenv.config({ path: path.resolve(__dirname, '..', '.env') });
+const defaultTokenDir = path.join(process.env.XDG_CONFIG_HOME || path.join(homedir(), '.config'), 'mcp-google-multi', 'tokens');
 const tokenDir = process.env.TOKEN_STORE_PATH
     ? path.resolve(process.env.TOKEN_STORE_PATH)
-    : path.resolve(__dirname, '..', 'tokens');
+    : defaultTokenDir;
 /**
  * Parse accounts from the GOOGLE_ACCOUNTS env var.
  * Format: "alias1:email1,alias2:email2,..."

package/dist/auth.d.ts

@@ -10,6 +10,4 @@ export declare function getAdminAccounts(): string[];
  * Resolves env flags: GOOGLE_OPTIONAL_SCOPES (global) and GOOGLE_ADMIN_ACCOUNTS (per-account allowlist).
  */
 export declare function resolveScopesForAccount(alias: string): string[];
-/** True if admin writes are explicitly enabled. Default refuses to prevent accidents on small orgs. */
-export declare function adminWritesEnabled(): boolean;
 export declare function runAuthFlow(args: string[]): Promise<void>;

package/dist/auth.js

@@ -36,13 +36,6 @@ export const OPTIONAL_SCOPE_BUNDLES = {
         'https://www.googleapis.com/auth/chat.messages',
         'https://www.googleapis.com/auth/chat.messages.create',
     ],
-    // Alert Center's apps.alerts scope is NOT grantable through the interactive
-    // user-consent flow this server uses — it requires a service account with
-    // domain-wide delegation. It lives in its own opt-in bundle so it never
-    // blocks the working Admin SDK admin scopes. See README "Alert Center".
-    alertcenter: [
-        'https://www.googleapis.com/auth/apps.alerts',
-    ],
 };
 export const ADMIN_SCOPES = [
     'https://www.googleapis.com/auth/admin.reports.audit.readonly',
@@ -79,10 +72,6 @@ export function resolveScopesForAccount(alias) {
     }
     return Array.from(new Set(scopes));
 }
-/** True if admin writes are explicitly enabled. Default refuses to prevent accidents on small orgs. */
-export function adminWritesEnabled() {
-    return process.env.GOOGLE_ALLOW_ADMIN_WRITES === 'true';
-}
 export async function runAuthFlow(args) {
     const accountIdx = args.indexOf('--account');
     if (accountIdx === -1 || !args[accountIdx + 1]) {

package/dist/index.js

@@ -16,7 +16,7 @@ import { registerTasksTools } from './tools/tasks.js';
 import { registerMeetTools } from './tools/meet.js';
 import { registerFormsTools } from './tools/forms.js';
 import { registerChatTools } from './tools/chat.js';
-import { registerAdminTools, registerAlertCenterTools } from './tools/admin.js';
+import { registerAdminTools } from './tools/admin.js';
 import { getOptionalBundles, getAdminAccounts } from './auth.js';
 import { ToolRegistry } from './registry.js';
 import { resolvePolicy, isAllowed, describePolicy } from './write-control.js';
@@ -38,8 +38,6 @@ function buildRegistry(server, policy) {
         registerFormsTools(registry);
     if (optional.has('chat'))
         registerChatTools(registry);
-    if (optional.has('alertcenter'))
-        registerAlertCenterTools(registry);
     if (getAdminAccounts().length > 0)
         registerAdminTools(registry);
     return registry;

package/dist/tools/admin.d.ts

@@ -3,15 +3,6 @@ import type { ToolRegistry } from '../registry.js';
  * Admin SDK tools require Workspace super-admin (or delegated admin) privileges on the target account.
  * Personal `@gmail.com` accounts will 403 on every endpoint.
  *
- * Writes are gated behind GOOGLE_ALLOW_ADMIN_WRITES=true to prevent accidents on small orgs
- * (a stray users.update on a 3-person Workspace is a bad day).
+ * Writes (e.g. admin_users_update) are gated by write-control like any CUD tool.
  */
 export declare function registerAdminTools(server: ToolRegistry): void;
-/**
- * Alert Center tools. Gated behind the `alertcenter` optional bundle, NOT the
- * admin bundle: the apps.alerts scope cannot be granted via this server's
- * interactive user-consent OAuth flow — it requires a service account with
- * domain-wide delegation. Registered separately so a missing/ungrantable
- * apps.alerts scope never blocks the working Admin SDK admin tools.
- */
-export declare function registerAlertCenterTools(server: ToolRegistry): void;

package/dist/tools/admin.js

@@ -4,14 +4,12 @@ import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
-import { adminWritesEnabled } from '../auth.js';
 const accountEnum = z.enum(ACCOUNTS);
 /**
  * Admin SDK tools require Workspace super-admin (or delegated admin) privileges on the target account.
  * Personal `@gmail.com` accounts will 403 on every endpoint.
  *
- * Writes are gated behind GOOGLE_ALLOW_ADMIN_WRITES=true to prevent accidents on small orgs
- * (a stray users.update on a 3-person Workspace is a bad day).
+ * Writes (e.g. admin_users_update) are gated by write-control like any CUD tool.
  */
 export function registerAdminTools(server) {
     // ─── Reports / audit log ───────────────────────────────────────────────
@@ -125,7 +123,7 @@ export function registerAdminTools(server) {
         }
     });
     server.registerTool('admin_users_update', {
-        description: 'Update a Workspace user (PATCH semantics). GATED: requires GOOGLE_ALLOW_ADMIN_WRITES=true to prevent accidental destructive ops on small orgs.',
+        description: 'Update a Workspace user (PATCH semantics). Gated by write-control (a CUD tool).',
         inputSchema: {
             account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
             userKey: z.string().describe('User email or ID'),
@@ -138,18 +136,6 @@ export function registerAdminTools(server) {
         },
     }, async ({ account, userKey, givenName, familyName, suspended, password, changePasswordAtNextLogin, orgUnitPath }) => {
         try {
-            if (!adminWritesEnabled()) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                error: 'admin_writes_disabled',
-                                hint: 'Admin write operations are disabled by default. Set GOOGLE_ALLOW_ADMIN_WRITES=true in .env and restart to enable.',
-                            }),
-                        }],
-                    isError: true,
-                };
-            }
             const auth = await getClient(account);
             const directory = google.admin({ version: 'directory_v1', auth });
             const requestBody = {};
@@ -242,67 +228,6 @@ export function registerAdminTools(server) {
         }
     });
 }
-/**
- * Alert Center tools. Gated behind the `alertcenter` optional bundle, NOT the
- * admin bundle: the apps.alerts scope cannot be granted via this server's
- * interactive user-consent OAuth flow — it requires a service account with
- * domain-wide delegation. Registered separately so a missing/ungrantable
- * apps.alerts scope never blocks the working Admin SDK admin tools.
- */
-export function registerAlertCenterTools(server) {
-    server.registerTool('alertcenter_alerts_list', {
-        description: 'List Workspace security alerts (suspicious login, phishing, leaked password, Drive exfil, etc.). Requires the alertcenter bundle + service-account domain-wide delegation.',
-        inputSchema: {
-            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
-            pageSize: z.number().min(1).max(1000).optional(),
-            pageToken: z.string().optional(),
-            filter: z.string().optional().describe('Filter expression, e.g. "type = \\"Suspicious login\\""'),
-            orderBy: z.string().optional(),
-            customerId: z.string().optional(),
-        },
-    }, async ({ account, pageSize, pageToken, filter, orderBy, customerId }) => {
-        try {
-            const auth = await getClient(account);
-            const alertcenter = google.alertcenter({ version: 'v1beta1', auth });
-            const res = await alertcenter.alerts.list({
-                pageSize: pageSize ?? 50,
-                pageToken,
-                filter,
-                orderBy,
-                customerId,
-            });
-            return {
-                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
-            };
-        }
-        catch (error) {
-            return handleAlertCenterError(error, account);
-        }
-    });
-    server.registerTool('alertcenter_alert_get', {
-        description: 'Get a single alert by ID. Requires the alertcenter bundle + service-account domain-wide delegation.',
-        inputSchema: {
-            account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
-            alertId: z.string().describe('Alert ID'),
-            customerId: z.string().optional(),
-        },
-    }, async ({ account, alertId, customerId }) => {
-        try {
-            const auth = await getClient(account);
-            const alertcenter = google.alertcenter({ version: 'v1beta1', auth });
-            const res = await alertcenter.alerts.get({ alertId, customerId });
-            return {
-                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
-            };
-        }
-        catch (error) {
-            return handleAlertCenterError(error, account);
-        }
-    });
-}
 function handleAdminError(error, account) {
     return handleGoogleApiError(error, account, "Admin tools require Workspace super-admin privileges AND the account must be listed in GOOGLE_ADMIN_ACCOUNTS (then re-authenticated). Personal Gmail accounts cannot use these endpoints.");
 }
-function handleAlertCenterError(error, account) {
-    return handleGoogleApiError(error, account, "Alert Center (apps.alerts) is not grantable via this server's user-consent OAuth flow — it requires a service account with domain-wide delegation. Enabling GOOGLE_OPTIONAL_SCOPES=alertcenter only declares the scope; the API will reject user-OAuth tokens. See README \"Alert Center\".");
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-google-multi",
-  "version": "4.5.0-alpha.3",
-  "description": "MCP server for Gmail, Google Drive, Calendar, Sheets, Docs, and Contacts with multi-account support",
+  "version": "5.0.0-beta.1",
+  "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -36,6 +36,12 @@
     "google-sheets",
     "google-docs",
     "google-contacts",
+    "google-workspace",
+    "google-tasks",
+    "google-meet",
+    "search-console",
+    "oauth",
+    "mcp-server",
     "claude",
     "claude-code"
   ],