Skip to content
Back to search

gum

CLI and MCP server for discovering and calling Google APIs from agents and scripts.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ehmo/gum with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ehmo/gum'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ehmo--gum/badge.svg)](/listings/ehmo--gum)

HTML

<a href="/listings/ehmo--gum"><img src="/api/listings/ehmo--gum/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Public release assets are published on the [GitHub releases page](https://github.com/ehmo/gum/releases). Download the archive for your OS and CPU, then verify it with `checksums.txt`.

tar -xzf gum_<version>_<os>_<arch>.tar.gz
install -m 0755 gum ~/.local/bin/gum
gum --version

Install the latest release with:

curl -fsSL https://raw.githubusercontent.com/ehmo/gum/main/install.sh | bash

Pin a version with `GUM_VERSION=vX.Y.Z`.

Homebrew:

brew tap ehmo/tap https://github.com/ehmo/homebrew-tap
brew install ehmo/tap/gum
gum setup --dry-run
gum doctor

Use the qualified formula name. Plain `brew install gum` installs Charmbracelet's `gum`, which is a different CLI.

The public repo also includes `Formula/gum.rb` for people who want to tap this repo directly and build from source. The `ehmo/tap/gum` formula installs from the release archives and is the normal Homebrew path.

The source tree uses a Go module under `apps/gum`, so this release does not document a `go install` path. Use release archives for a stamped binary.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 408 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # gum
  2. <p align="center">
  3. <img alt="gum logo" src="docs/assets/gum-logo.png" width="320">
  4. </p>
  5. <p align="center">
  6. <img alt="Go 1.26" src="https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white">
  7. <img alt="MIT license" src="https://img.shields.io/badge/license-MIT-2ea44f">
  8. <img alt="MCP stdio" src="https://img.shields.io/badge/MCP-stdio-7c3aed">
  9. <img alt="agent skills" src="https://img.shields.io/badge/agent%20skills-included-f97316">
  10. </p>
  11. Most agents can write code. Giving them access to Google APIs is the risky part.
  12. The hard part is not sending HTTP. The hard part is finding the right method,
  13. getting the right OAuth scope, trimming huge JSON responses, and stopping a bad
  14. prompt from turning into a real delete.
  15. gum is a single binary that gives agents and humans a safer control surface for
  16. Google APIs. It runs as a terminal CLI and as an MCP stdio server. It carries an
  17. embedded Google API catalog, local auth helpers, compact output shaping, and
  18. confirmation gates for risky writes.
  19. Use gum when you want an agent to inspect Gmail, Drive, Docs, Sheets, Calendar,
  20. Admin, or other Google services without pasting tokens into prompts or writing a
  21. custom tool for each endpoint.
  22. Use it only with Google accounts, projects, and APIs you own or are authorized
  23. to operate.
  24. ## Find your task
  25. - [Keyword Planner](docs/keyword-planner.md): keyword ideas, monthly search volume, and ad forecasts.
  26. - [Search Console](docs/search-console.md): organic clicks, impressions, rankings, and URL inspection.
  27. - [Google Ads](docs/services/googleads.md): campaign, keyword, search-term, and spend reports.
  28. - [Data Manager](docs/services/datamanager.md): offline conversions and diagnostics.
  29. - [All services](docs/services/README.md): mail, calendars, files, spreadsheets, and other products.
  30. ## What gum covers
  31. gum v2.3.3 ships with 228 operations across 33 services. See the
  32. [release notes](docs/release-notes-v2.3.3.md) and
  33. [operations by service](docs/services/README.md).
  34. | Surface | Examples | Auth |
  35. | --- | --- | --- |
  36. | Google Workspace and Google APIs | Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, Admin, Vault, Chat, Meet, Classroom, Forms, Apps Script, People, Photos, YouTube, Search Console, Google Ads, Data Manager, Maps, Custom Search | OAuth, ADC, API key, service account, or Google Ads developer token |
  37. | Bundled plugin services | Google Flights, Google Scholar, Google Patents, Google Trends, YouTube transcripts | Plugin-managed setup, with separate trust and sandbox checks |
  38. The Google API path is for accounts and projects you control. The plugin path is
  39. for useful Google-adjacent services that do not fit the normal OAuth catalog
  40. model.
  41. ```mermaid
  42. flowchart LR
  43. User["Agent or CLI user"] --> Gum["gum"]
  44. Gum --> Catalog["API catalog<br/>228 ops / 33 services"]
  45. Gum --> Auth["Auth resolver<br/>OAuth / ADC / API key / service account"]
  46. Gum --> Gates["Risk gates<br/>write + destructive confirmation"]
  47. Gum --> Shape["Output shaping<br/>small MCP-friendly results"]
  48. Catalog --> Google["Google APIs"]
  49. Auth --> Google
  50. Gates --> Google
  51. Google --> Shape
  52. Shape --> User
  53. Gum --> Plugins["Bundled plugins<br/>Flights / Scholar / Patents / Trends"]
  54. Plugins --> Shape
  55. ```
  56. ## Why this is different
  57. Without gum, an agent usually gets one of two bad choices:
  58. - A giant tool list, where every Google method burns context before the task
  59. starts.
  60. - A raw HTTP escape hatch, where the agent has to infer scopes, paths, request
  61. bodies, pagination, and delete safety on the fly.
  62. gum keeps the first screen small. The MCP server starts with 29 tools: 9
  63. meta-tools, 18 common convenience tools, and 2 skill helpers. Everything else is
  64. found through `gum.search_apis` and loaded only when needed.
  65. `gum gain --fixture-replay` runs the deterministic local replay for the current
  66. checkout. Treat gain output as a regression signal tied to the binary, fixture
  67. set, and format you ran, not as a billing promise or latency claim.
  68. ## How OAuth works
  69. OAuth is Google's consent flow. A Google Cloud project owns an OAuth client, the
  70. consent screen, API enablement, quota, and verification state. gum asks you
  71. to use your own Desktop OAuth client because that keeps those controls in your
  72. project.
  73. The flow is:
  74. 1. You create a Google Cloud project and Desktop OAuth client.
  75. 2. You enable the APIs you want gum to call.
  76. 3. You register the client once with `gum auth use-oauth-client`.
  77. 4. `gum login --service <name>` opens your browser and stores the resulting
  78. refresh token in the OS keychain.
  79. 5. CLI, MCP, and agent calls reuse that local credential without putting tokens
  80. in prompts.
  81. Not every Google surface uses the same auth shape. Some operations use OAuth.
  82. Some use ADC, API keys, service accounts, or Google Ads developer tokens. The
  83. bundled plugin services, such as Flights and Scholar, use their own setup path
  84. because they are not normal Google API catalog endpoints.
  85. ## Add gum to an agent
  86. Install the bundled skills and MCP server config in one step:
  87. ```shell
  88. gum setup --dry-run
  89. gum setup --target all --features skills,mcp --yes
  90. gum agents install --target all --features skills,mcp --dry-run --format json
  91. ```
  92. Use `--target codex`, `claude`, `cursor`, or `gemini` to install for one
  93. agent. Use `--scope project` when you want repo-local MCP config. The default
  94. writes skill files plus a stdio MCP entry that runs `gum mcp --stdio`.
  95. Run the dry run first. It prints the exact files gum would write. Reruns are
  96. safe: MCP config files are merged, and existing skill files are left alone
  97. unless you pass `--force`.
  98. ## At a glance
  99. | Need | Use |
  100. | --- | --- |
  101. | Explore Google API operations | `gum search`, `gum describe` |
  102. | Call read/write/destructive APIs | `gum read`, `gum write`, `gum destructive` |
  103. | Agent access over MCP | `gum mcp --stdio` |
  104. | Guided setup and diagnostics | `gum setup`, `gum doctor` |
  105. | Google auth | Your Google OAuth client, ADC, API key, or service account |
  106. | Local state | Profiles under XDG config, data, and cache directories |
  107. | Secrets for agent workflows | [HASP](https://github.com/gethasp/hasp) for brokered local secret access |
  108. | Install and release downloads | Release archives, install script, or Homebrew tap |
  109. ## Install
  110. Public release assets are published on the
  111. [GitHub releases page](https://github.com/ehmo/gum/releases). Download the
  112. archive for your OS and CPU, then verify it with `checksums.txt`.
  113. ```shell
  114. tar -xzf gum_<version>_<os>_<arch>.tar.gz
  115. install -m 0755 gum ~/.local/bin/gum
  116. gum --version
  117. ```
  118. Install the latest release with:
  119. ```shell
  120. curl -fsSL https://raw.githubusercontent.com/ehmo/gum/main/install.sh | bash
  121. ```
  122. Pin a version with `GUM_VERSION=vX.Y.Z`.
  123. Homebrew:
  124. ```shell
  125. brew tap ehmo/tap https://github.com/ehmo/homebrew-tap
  126. brew install ehmo/tap/gum
  127. gum setup --dry-run
  128. gum doctor
  129. ```
  130. Use the qualified formula name. Plain `brew install gum` installs
  131. Charmbracelet's `gum`, which is a different CLI.
  132. The public repo also includes `Formula/gum.rb` for people who want to tap this
  133. repo directly and build from source. The `ehmo/tap/gum` formula installs from
  134. the release archives and is the normal Homebrew path.
  135. The source tree uses a Go module under `apps/gum`, so this release does not
  136. document a `go install` path. Use release archives for a stamped binary.
  137. ## First Proof
  138. For Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, and most Workspace
  139. APIs, gum needs a Google OAuth client from your Google Cloud project. Google
  140. uses that client to show the consent screen and issue your local refresh token.
  141. 1. Create a Google Cloud project.
  142. 2. Configure an OAuth consent screen.
  143. 3. Create an OAuth client ID with application type `Desktop app`.
  144. 4. Enable the Google APIs you plan to call.
  145. 5. Store the client in gum:
  146. ```shell
  147. printf '%s' "$GOOGLE_OAUTH_CLIENT_SECRET" \
  148. | gum auth use-oauth-client --client-id "$GOOGLE_OAUTH_CLIENT_ID" --secret-stdin
  149. ```
  150. Authorize a small Workspace scope set:
  151. ```shell
  152. gum login --service gmail,calendar
  153. gum doctor
  154. gum read gmail.users.messages.list --args '{"userId":"me","maxResults":5}'
  155. ```
  156. For exact API setup, see [docs/auth-guides](docs/auth-guides/README.md).
  157. ## Keep Secrets Out of Prompts
  158. gum stores Google refresh tokens in your OS keychain. It also accepts OAuth
  159. client secrets through stdin. That covers gum's own auth path.
  160. Your agent may still need other secrets: API tokens for tests, deploy keys,
  161. staging credentials, or service-specific config. Use
  162. [HASP](https://github.com/gethasp/hasp) for that job. HASP is a local secret
  163. broker for coding agents. It stores secrets in an encrypted vault, gives a
  164. command only the values it is allowed to use, and keeps managed secret values
  165. out of the agent's prompt.
  166. Install HASP:
  167. ```shell
  168. brew tap gethasp/homebrew-tap
  169. brew install hasp
  170. hasp setup
  171. ```
  172. Run gum work through a HASP grant when a task needs both Google API access and
  173. non-Google secrets:
  174. ```shell
  175. hasp secret add
  176. hasp run --project-root . \
  177. --env GUM_GOOGLE_ADS_DEVELOPER_TOKEN=@GOOGLE_ADS_DEVELOPER_TOKEN \
  178. --grant-project session \
  179. --grant-secret session \
  180. -- gum doctor
  181. ```
  182. Use three rules:
  183. - Put Google OAuth client secrets into gum with `--secret-stdin`, not in chat.
  184. - Put project and deploy secrets into HASP, not in `.env` files or prompts.
  185. - Give agents short-lived HASP grants for the command they need to run.
  186. See [docs/hasp.md](docs/hasp.md) for the gum + HASP workflow and the safety
  187. checklist.
  188. ## Which Auth Path Should I Use?
  189. | Use case | Path | Setup |
  190. | --- | --- | --- |
  191. | Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, YouTube, People, Photos, Chat, Classroom, Meet, Apps Script, Admin, Vault, Search Console, Google Ads | BYO OAuth | `gum auth use-oauth-client`, then `gum login --service <name>` |
  192. | Automation in Google Cloud | ADC | Set `GOOGLE_APPLICATION_CREDENTIALS` or use a gcloud ADC cache |
  193. | Maps and Custom Search | API key | `gum auth use-api-key --stdin` |
  194. | Service-account variants | Service account | `gum auth use-service-account <key.json>` |
  195. | Google Ads | BYO OAuth plus developer token | `gum auth use-ads-developer-token`, then `gum login --service googleads` |
  196. | Data Manager conversion ingestion and diagnostics | BYO OAuth with the separate `datamanager` scope | `gum login --service datamanager`; see the [setup guide](docs/auth-guides/google-ads.md#data-manager) |
  197. ## MCP Setup
  198. Use setup when you want gum to write common MCP client config files:
  199. ```shell
  200. gum setup --target all --features skills,mcp --dry-run
  201. gum setup --target all --features skills,mcp --yes
  202. ```
  203. Run the local server directly:
  204. ```shell
  205. gum mcp --stdio
  206. ```
  207. Add this server to your MCP client config:
  208. ```json
  209. {
  210. "mcpServers": {
  211. "gum": {
  212. "command": "gum",
  213. "args": ["mcp", "--stdio"]
  214. }
  215. }
  216. }
  217. ```
  218. Use an absolute binary path if another `gum` command is installed on your
  219. machine. The Charmbracelet project also uses the name `gum`.
  220. gum exposes a compact meta-tool surface plus selected convenience tools at
  221. startup. The meta-tools let clients search, describe, read, write, confirm
  222. destructive actions, run bounded code, inspect cache/gain state, and poll
  223. long-running work without loading the full catalog into context. The server
  224. also exposes `skills_list` and `skills_get` so MCP clients can load the current
  225. agent guidance from the installed binary. Use `gum mcp --stdio --help`,
  226. `gum skills list`, and `gum describe <op_id>` for the exact shipped surface.
  227. More client snippets are in [docs/mcp-client-setup.md](docs/mcp-client-setup.md).
  228. ## CLI Basics
  229. ```shell
  230. gum search "gmail messages"
  231. gum describe gmail.users.messages.list
  232. gum read gmail.users.messages.list --args '{"userId":"me","maxResults":5}'
  233. gum write <op_id> --args '<json>'
  234. gum destructive <op_id> --args '<json>'
  235. gum doctor --format=json
  236. ```
  237. Run `gum init --target claude-code` to patch an MCP config and write a local
  238. `GUM.md` operator note. It shows the diff before it edits files unless you pass
  239. `--yes`. New installs should start with `gum setup`; `gum init` remains for
  240. the older direct Claude/Cursor patch flow.
  241. ## Troubleshooting
  242. ### `AUTH_REQUIRED` or `SCOPE_MISSING`
  243. The active credential cannot satisfy the operation.
  244. ```shell
  245. gum auth status
  246. gum login --service gmail,calendar
  247. gum auth probe --scopes gmail.readonly
  248. ```
  249. If gum says a BYO OAuth client is missing, create a Google Desktop OAuth client
  250. and run:
  251. ```shell
  252. printf '%s' "$GOOGLE_OAUTH_CLIENT_SECRET" \
  253. | gum auth use-oauth-client --client-id "$GOOGLE_OAUTH_CLIENT_ID" --secret-stdin
  254. ```
  255. If gum says a service needs product setup, OAuth worked but Google rejected the
  256. request for a service-specific reason. Examples include Chat app installation,
  257. Photos Library app access, Search Console property verification, and Google Ads
  258. developer-token approval.
  259. ### `RATE_LIMITED`
  260. Google returned HTTP 429 or a local rate-limit bucket ran out. gum retries
  261. transient 429 responses with jittered backoff. Persistent 429 means the Google
  262. project quota is too low.
  263. Lower request concurrency, retry later, or raise quota in Google Cloud Console.
  264. ### MCP Client Does Not See Tools
  265. 1. Run `gum mcp --stdio --help`.
  266. 2. Use an absolute binary path in the MCP config.
  267. 3. Restart the MCP client. Tool registration happens at session start.
  268. 4. Check the client's stderr log for handshake errors.
  269. ### Destructive Confirmation Fails
  270. Destructive tokens are single-use. Run the command once without `--confirmed`
  271. to get a fresh `confirmation_token`, then retry with:
  272. ```shell
  273. gum destructive <op_id> --confirmed --token <confirmation_token> --args '<json>'
  274. ```
  275. ## Development
  276. ```shell
  277. cd apps/gum
  278. go test ./...
  279. ```
  280. Useful release gates:
  281. ```shell
  282. make test-matrix
  283. make coverage-floor
  284. go vet ./...
  285. ```
  286. The embedded catalog is generated under `apps/gum/internal/embedded`:
  287. ```shell
  288. cd apps/gum
  289. go run ./cmd/gen-catalog -out internal/embedded/catalog.json
  290. ```
  291. ## Repo Layout
  292. ```text
  293. apps/gum/ Go module for the CLI and MCP server
  294. apps/gum/cmd/gum/ Cobra entry point
  295. apps/gum/internal/auth/ BYO OAuth, ADC, API key, service account auth
  296. apps/gum/internal/mcp/ MCP server presentation layer
  297. apps/gum/internal/dispatch/ Shared dispatch kernel
  298. docs/auth-guides/ Public Google credential setup guides
  299. docs/commands/ Generated command reference from `gum schema --json`
  300. docs/index.md Docs-site overview
  301. docs/mcp-client-setup.md Public MCP client setup
  302. docs/ Public auth, MCP, catalog, plugin, and test references
  303. ```
  304. ## Security
  305. See [SECURITY.md](SECURITY.md).
  306. ## License
  307. gum is licensed under the MIT License. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.