feat(mcp): add typed allowlisted server

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- MCP: add a typed, allowlisted `gog mcp` stdio server with read-only defaults and explicit write-tool opt-in. (#637) — thanks @auroracapital.
 - Docs: add `docs table-column-width` to set fixed native table column widths or reset columns to evenly distributed sizing. (#631) — thanks @sebsnyk.
 
 ### Fixed

README.md

@@ -13,6 +13,8 @@ It is built for terminals, shell scripts, CI, and coding agents:
 - multiple Google accounts and OAuth clients
 - OAuth, direct access tokens, ADC, and Workspace service accounts
 - runtime command allowlists/denylists and baked safety-profile binaries
+- typed [MCP server](docs/mcp.md) for agent clients, read-only by default and
+  without a generic command runner
 - read-only audit/reporting commands for risky surfaces like Drive and Contacts
 - [generated docs](docs/commands/README.md) for every command
 
@@ -23,6 +25,7 @@ Start here:
 - [Install](docs/install.md)
 - [Quickstart](docs/quickstart.md)
 - [Auth clients and service accounts](docs/auth-clients.md)
+- [MCP server](docs/mcp.md)
 - [Command index](docs/commands/README.md)
 - [Gmail watch / Pub/Sub push](docs/watch.md) (<https://gogcli.sh/watch.html>)
 
@@ -411,6 +414,28 @@ gog --json gmail search 'newer_than:7d'
 For stricter agent deployments, build or download a baked safety-profile binary.
 See [docs/safety-profiles.md](docs/safety-profiles.md).
 
+### MCP server
+
+`gog mcp` exposes a typed MCP stdio server for agent clients. It registers
+specific Google tools such as `gmail_search`, `docs_get`, and
+`sheets_read_range`; it does not expose a generic `gog_exec` or arbitrary
+command bridge.
+
+```bash
+# Read-only server.
+gog --account you@gmail.com mcp
+
+# Docs tools only; writes require explicit opt-in.
+gog --account you@gmail.com \
+  --enable-commands-exact docs.cat,docs.write \
+  mcp \
+  --allow-write \
+  --allow-tool docs.*
+```
+
+See [docs/mcp.md](docs/mcp.md) for client config, tool selection, safety
+behavior, mcporter examples, and troubleshooting.
+
 ## Auth and Accounts
 
 Docs: [Auth clients](docs/auth-clients.md),

docs/commands.generated.md

@@ -435,6 +435,7 @@ Generated from `gog schema --json`.
       - [`gog maps (map) places (place) details (get,info,show) <placeId> [flags]`](commands/gog-maps-places-details.md) - Get Place details
       - [`gog maps (map) places (place) search (find) <query> ... [flags]`](commands/gog-maps-places-search.md) - Search Places by text
     - [`gog maps (map) reverse-geocode (reverse) --lat=STRING --lng=STRING [flags]`](commands/gog-maps-reverse-geocode.md) - Convert coordinates to an address
+  - [`gog mcp [flags]`](commands/gog-mcp.md) - Run a typed, allowlisted MCP server over stdio
   - [`gog me [flags]`](commands/gog-me.md) - Show your profile (alias for 'people me')
   - [`gog meet (meeting) <command> [flags]`](commands/gog-meet.md) - Google Meet
     - [`gog meet (meeting) create (new) [flags]`](commands/gog-meet-create.md) - Create a meeting space

docs/commands/README.md

@@ -2,7 +2,7 @@
 
 Every `gog` command has a generated docs page. The source of truth is the live CLI schema; run `make docs-commands` after changing command names, flags, help text, aliases, or arguments.
 
-Generated pages: 582.
+Generated pages: 583.
 
 ## Top-level Commands
 
@@ -30,6 +30,7 @@ Generated pages: 582.
 - [gog logout](gog-logout.md) - Remove a stored refresh token (alias for 'auth remove')
 - [gog ls](gog-ls.md) - List Drive files (alias for 'drive ls')
 - [gog maps](gog-maps.md) - Google Maps
+- [gog mcp](gog-mcp.md) - Run a typed, allowlisted MCP server over stdio
 - [gog me](gog-me.md) - Show your profile (alias for 'people me')
 - [gog meet](gog-meet.md) - Google Meet
 - [gog open](gog-open.md) - Print a best-effort web URL for a Google URL/ID (offline)
@@ -486,6 +487,7 @@ Generated pages: 582.
       - [gog maps places details](gog-maps-places-details.md) - Get Place details
       - [gog maps places search](gog-maps-places-search.md) - Search Places by text
     - [gog maps reverse-geocode](gog-maps-reverse-geocode.md) - Convert coordinates to an address
+  - [gog mcp](gog-mcp.md) - Run a typed, allowlisted MCP server over stdio
   - [gog me](gog-me.md) - Show your profile (alias for 'people me')
   - [gog meet](gog-meet.md) - Google Meet
     - [gog meet create](gog-meet-create.md) - Create a meeting space

docs/commands/gog-mcp.md

@@ -0,0 +1,50 @@
+# `gog mcp`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Run a typed, allowlisted MCP server over stdio
+
+## Usage
+
+```bash
+gog mcp [flags]
+```
+
+## Parent
+
+- [gog](gog.md)
+
+## Flags
+
+| Flag | Type | Default | Help |
+| --- | --- | --- | --- |
+| `--access-token` | `string` |  | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
+| `-a`<br>`--account`<br>`--acct` | `string` |  | Account email for API commands (gmail/calendar/chat/classroom/drive/drivelabels/docs/slides/contacts/tasks/people/sheets/forms/sites/appscript/analytics/searchconsole/ads/photos) |
+| `--allow-tool`<br>`--tool` | `[]string` |  | Tool or service allowlist (default: all read-only tools). Examples: gmail.*,docs_get,sheets |
+| `--allow-write` | `bool` |  | Expose write tools. Write tools must also match --allow-tool when that flag is set. |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--disable-commands` | `string` |  | Comma-separated list of disabled commands; dot paths allowed |
+| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` |  | Do not make changes; print intended actions and exit successfully |
+| `--enable-commands` | `string` |  | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
+| `--enable-commands-exact` | `string` |  | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
+| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
+| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
+| `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
+| `--home` | `string` |  | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--list-tools` | `bool` |  | Print enabled MCP tools as JSON and exit |
+| `--max-output-bytes` | `int` | 102400 | Max stdout/stderr bytes captured per tool call |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
+| `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
+| `--timeout-seconds` | `int` | 60 | Per-tool subprocess timeout |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
+
+## See Also
+
+- [gog](gog.md)
+- [Command index](README.md)

docs/commands/gog.md

@@ -40,6 +40,7 @@ gog <command> [flags]
 - [gog logout](gog-logout.md) - Remove a stored refresh token (alias for 'auth remove')
 - [gog ls](gog-ls.md) - List Drive files (alias for 'drive ls')
 - [gog maps](gog-maps.md) - Google Maps
+- [gog mcp](gog-mcp.md) - Run a typed, allowlisted MCP server over stdio
 - [gog me](gog-me.md) - Show your profile (alias for 'people me')
 - [gog meet](gog-meet.md) - Google Meet
 - [gog open](gog-open.md) - Print a best-effort web URL for a Google URL/ID (offline)

docs/index.md

@@ -46,6 +46,7 @@ gog slides create-from-markdown "Weekly update" --content-file slides.md
 
 - **Trying it.** [Install](install.md) → [Quickstart](quickstart.md). Five minutes from `brew install` to your first authenticated query.
 - **Wiring up an agent.** [Safety Profiles](safety-profiles.md) and the bundled [`gog` agent skill](https://github.com/openclaw/gogcli/blob/main/.agents/skills/gog/SKILL.md). Lock the binary down before handing it to a model.
+- **Serving MCP tools.** [MCP server](mcp.md) exposes typed, allowlisted tools for agent clients without a generic command bridge.
 - **Persisting auth and state.** [Paths and State](paths.md) covers `GOG_HOME`, per-kind directories, XDG paths, and legacy compatibility.
 - **Running Workspace at scale.** [Auth Clients](auth-clients.md) for service accounts, named OAuth clients, and domain-wide delegation.
 - **Managing Workspace.** [Workspace Admin](workspace-admin.md) covers user creation, cleanup, organizational units, and group administration.