grr-cli MCP server
Commit Nov 15, 2026Provides a command-line interface to interact with 14 Google APIs using a single OAuth login and a generated command tree.
Also known as debanjanbasu/grr-cli
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is grr-cli MCP?
grr-cli provides a command-line interface to interact with 14 Google APIs using a single OAuth login and a generated command tree.
Summary generated from the project's README
About grr-cli MCP server
Developers can manage fourteen different Google APIs through a single command-line interface using grr-cli. This tool provides a unified command tree generated directly from Google's Discovery Service, allowing for high-performance interactions with services like Gmail, Drive, Calendar, and Sheets. It is designed to be used locally via a terminal, offering machine-readable output that is ideal for automation and scripting.
Setting up the tool is straightforward because prebuilt release binaries come with an OAuth client already compiled in, requiring only a single login command to begin. For those building from source, the server supports custom configuration through environment variables or a config file. Users can also utilize the grr ask feature to route natural language requests to specific API methods by connecting to a System One provider with a TypeSafe API key. This approach ensures that the AI only selects from valid, existing methods and parameters provided by the CLI.
What you can do with it
- 1List Gmail messagesAn AI client can retrieve a specific number of unread messages from a user's inbox.
- 2Browse Google Drive filesA developer can request a list of files from their Google Drive with a defined page size.
- 3Execute natural language requestsUsers can type plain English commands to have the CLI automatically select the correct API method and parameters.
- 4Inspect API documentationYou can describe specific API methods to understand their available parameters and functionality.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
TYPESAFE_API_KEY
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledebanjanbasu/grr-cli is public and reachablegithub.com/debanjanbasu/grr-cli ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/debanjanbasu/grr-cli ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubgrr
Google tools from the terminal, at maximum performance. grr-cli is one published Rust package built around the grr command-line binary. Fourteen Google APIs share one OAuth login and one command tree — generated straight from Google's own Discovery Service — while stdout stays clean and machine-readable.
Project site: grr-cli.pages.dev · Privacy
grr is an independent project and is not affiliated with or endorsed by Google.
grr auth login
grr gmail users messages list --user-id me --q "in:inbox" --max-results 5
grr drive files list --page-size 10
grr api describe calendar.events.list
grr schema
Install
Prebuilt binaries — macOS arm64, Linux x86_64, Linux aarch64, Windows x86_64, and Windows on ARM (aarch64): GitHub Releases
Release binaries are zero-config — an OAuth client is compiled in, so grr auth login works immediately. Archives are .tar.zst (zstd level 22) on unix and .zip on Windows; binaries are UPX-packed with --best --lzma where the compressor supports it — the workflow verifies the packed copy still executes and falls back to the unpacked binary with a warning if not.
From source (the default CLI build requires Rust nightly — see Development):
cargo install --git https://github.com/debanjanbasu/grr-cli
or from a local clone at the repository root:
git clone https://github.com/debanjanbasu/grr-cli
cd grr-cli
cargo install --path .
A source build has no OAuth client compiled in — see Authentication and configuration.
Package managers:
winget install debanjanbasu.grr # Windows (manifest not yet published — submission automated via REPO_WINGET_TOKEN; see Packaging & status)
cargo install grr-cli # crates.io
Homebrew (macOS + Linux), from the debanjanbasu/tap tap:
brew tap debanjanbasu/tap
brew trust debanjanbasu/tap
brew install grr
brew trust is required, not decorative: since Homebrew 4.4 third-party taps are untrusted by default, and brew install refuses to install a formula from an untrusted tap until you trust it once. Skipping that line is the most common first-run failure.
The crates.io CLI build needs nightly Rust and RUSTFLAGS="--cfg reqwest_unstable" for HTTP/3; the prebuilt releases avoid that source-build step. cargo install also produces a binary with no embedded OAuth client, so budget five minutes for grr auth setup (or a .env) on that path.
Shell completions — grr completions <shell> prints scripts from the same tree as grr --help. Bash and zsh: write the script once (refresh after upgrading); both load it lazily (the zsh script is ~2.6 MB). PowerShell and Elvish snippets below run the generator on each shell startup.
# zsh: any directory on $fpath; if ~/.zfunc is not on it yet, add
# `fpath=(~/.zfunc $fpath)` to ~/.zshrc ABOVE compinit (or oh-my-zsh's source line)
mkdir -p ~/.zfunc && grr completions zsh > ~/.zfunc/_grr
# bash (bash-completion 2.x loads this lazily)
mkdir -p ~/.local/share/bash-completion/completions
grr completions bash > ~/.local/share/bash-completion/completions/grr
# PowerShell: add to $PROFILE
grr completions powershell | Out-String | Invoke-Expression
# elvish: add to rc.elv
eval (grr completions elvish | slurp)
Fish is not supported yet: clap_complete's fish generator stops below two levels of subcommand nesting, and grr's methods sit three to five levels deep.
60-second quickstart
brew tap debanjanbasu/tap
brew trust debanjanbasu/tap
brew install grr
grr auth login
grr gmail users getProfile --user-id me
There is nothing to configure first: a release binary already carries an OAuth client, so grr auth login opens the browser, you consent, and every service works. Headless machine? grr auth login --device prints a URL + code instead of opening a browser — that flow authenticates as a separate client of type TVs and Limited Input devices (Google's device endpoint rejects the Desktop client with Invalid client type), which release binaries also carry; a source build supplies it with GRR_DEVICE_CLIENT_ID / GRR_DEVICE_CLIENT_SECRET. Google also caps what that flow may ask for: only drive.file, calendar, calendar.readonly, the legacy Calendar/Contacts feeds, userinfo and openid are grantable, so a device login asks for the same flag-derived set the browser flow would (--service / --all-scopes work here too) intersected with that allowlist — one scope outside it fails the whole request. Gmail, Chat, Docs, Sheets, Slides, Tasks, Forms, Apps Script, Analytics and the admin APIs still need the browser flow, and --device --all-scopes will not get them.
Building from source instead of installing a release? Read Authentication and configuration before your first grr invocation.
Authentication and configuration
Release binaries are zero-config. build.rs reads GRR_CLIENT_ID / GRR_CLIENT_SECRET from the build environment — GitHub Actions repo secrets for the official builds — and compiles them in, so GitHub Releases and Homebrew installs need no config file and no console visit.
Source builds bring their own client. cargo install grr-cli compiles the published sources with nothing in the build environment, so that binary has no embedded client. Any one of these fixes it:
- A
.envnext toCargo.toml— copy.env.exampleto.env, fill in both values, rebuild.build.rsreads the environment first and.envsecond, so every build after that is zero-config too..envis gitignored; never commit it. - Environment variables for a single build —
GRR_CLIENT_ID=… GRR_CLIENT_SECRET=… cargo build --release. grr auth setup— no rebuild required, because it writes~/.grr/config.toml(Windows:%USERPROFILE%\.grr\config.toml) instead.
grr auth setup
Create and store an OAuth client. Release builds ship with one, so this is only needed when using
your own client
Usage: grr auth setup [OPTIONS]
Options:
--client-id <CLIENT_ID> Google OAuth client id (…apps.googleusercontent.com).
Prompted for when omitted
--client-secret <CLIENT_SECRET> Google OAuth client secret. Prompted for when omitted
--print-only Print the instructions and the resolved path, but write
nothing. Useful for a first look, and for agents that only
want the recipe
--force Overwrite an existing ~/.grr/config.toml instead of refusing
--enable-apis Try `gcloud services enable` for the APIs when gcloud is on
PATH
-f, --format <FORMAT> Output format [default: json] [possible values: json, jsonl,
table, pretty]
--readonly Refuse every write method (POST/PATCH/PUT/DELETE); only reads
run
--deny-service <SERVICE> Refuse every method of this service (repeatable)
--deny-verb <VERB> Refuse this HTTP verb (repeatable)
-h, --help Print help
It checks the client-id shape before writing anything (must end in .apps.googleusercontent.com, and a truncated paste is rejected), rejects a truncated secret, writes the file mode 0600 on unix, and refuses to clobber an existing config.toml without --force. It prints the exact Cloud Console URLs and the gcloud services enable line covering every API behind a command — gmail, calendar-json, drive, people, chat, forms, tasks, docs, sheets, slides, script, analyticsadmin, analyticsdata, and searchconsole …googleapis.com — and --print-only hands you that recipe without touching disk, which is the right first command when you have no client at all:
grr auth setup --print-only
Because it runs before any client is resolved, grr auth setup works even when nothing is configured yet: it is the escape hatch, not a last resort. Under a non-TTY stdin (CI, agents, pipes) it errors instead of hanging, so pass --client-id and --client-secret explicitly rather than relying on the prompts.
Resolution order at runtime: GRR_OAUTH__CLIENT_ID / GRR_OAUTH__CLIENT_SECRET → ~/.grr/config.toml → the client compiled into the binary (env wins over the file; the compiled-in client is the fallback). GRR_CONFIG_PATH moves the file; RUST_LOG sets the log level.
Embedding a client secret is acceptable here because Google treats installed-app client secrets as non-confidential — the flow is protected by PKCE, which is always on. The secret lives in GitHub Actions repo secrets and is compiled in at release time; it must never enter the repository or a CI log.
To create a client from scratch, follow docs/gcp-setup.md — you only need that if you are building from source or deliberately want your own client.
The project/fork is Google Rust Rewrite; the Google consent-screen application is named Rust Rewrite. The consent screen is where that shorter name appears.
grr ask and System One (JEV)
grr ask "<request>" routes plain words to a typed method + parameters and prints the plan; --run executes it through the same call path as grr api. Routing is three System One judgments — service, then method, then parameters — each a small HTTP request. The model only ever selects among candidates the CLI supplies: the 14 services, a service's methods, a parameter's enum values or spans found in your request. It cannot invent a method id or a value — the CLI decides what runs.
Set TYPESAFE_API_KEY and it works against TypeSafe's hosted Jev:
export TYPESAFE_API_KEY=...
grr ask "show my unread messages"
The env route is preferred: a key in a config file can leak with the file. The [systemone] block in ~/.grr/config.toml is the only other surface:
| Key | Default | Meaning |
|---|---|---|
endpoint |
https://api.typesafe.ai/v1/systemone |
any provider speaking the System One contract (POST state + typed questions, back structured answers) |
model |
jev-latest |
model name sent to that endpoint |
api-key |
— | sent as Authorization: Bearer; empty behaves as absent |
confidence-threshold |
0.6 |
below this method-choice confidence the plan is flagged, never blocked |
Any key also accepts the generic GRR_SYSTEMONE__ENDPOINT / GRR_SYSTEMONE__MODEL / GRR_SYSTEMONE__API_KEY env form (the same GRR_ route as GRR_OAUTH__*), and TYPESAFE_API_KEY overrides api-key. The key never appears in the printed plan or in a request body — it rides only in the Authorization header.
Pointing endpoint/model at your own provider changes only which model ranks the CLI-supplied candidates; the candidate sets, the typed parameter fill, and what actually executes stay grr's. grr ask honors the global safety flags (--readonly, --deny-service <name>, --deny-verb <VERB>) whether or not you pass --run, and the gate runs as soon as the method is resolved — before the parameter-fill judgment and before any Google request is built or sent.
Usage highlights
grr gmail users messages list --user-id me --q "from:github.com" --max-results 10
grr gmail users messages get --user-id me --id 191f8ab2 --param-format metadata
grr gmail users threads list --user-id me --max-results 10
grr calendar events list --calendar-id primary --time-min 2026-10-01T00:00:00Z --max-results 10
grr drive files list --q "name contains 'report'" --page-size 10
grr drive files export --file-id <id> --mime-type application/pdf
grr chat spaces messages create --parent spaces/AAAA --body-file ./message.json
grr sheets spreadsheets values get --spreadsheet-id 1AbC… --range Sheet1!A1:B10
grr tasks tasklists list
grr transport
grr schema
Every command that prints data takes -f/--format json|jsonl|table|pretty (default json); grr transport, grr completions and grr skills install print plain text instead. For gmail users messages get, the Gmail MIME parameter named format arrives as --param-format full|metadata|minimal|raw (see the collision rule below), while -f/--format still selects the printed output format. Logs go to stderr, so stdout is always parseable:
grr gmail users messages list --user-id me --q "in:inbox" --max-results 1 | jq -r '.[0].id'
grr --version prints the semver on its first line (scripts depend on that), then the crab mascot: in full 24-bit-colour pixel art on a terminal that advertises COLORTERM/direct colour, and as plain ASCII everywhere else — a pipe, TERM=dumb, or NO_COLOR. Set CLICOLOR_FORCE=1 to force the colour logo through a pipe (grr --version | less -R); NO_COLOR still wins over it.
Command reference
The command tree is generated from the committed Discovery index by scripts/generate-commands.ts (CI-gated with --check), so this table is deliberately coarse: grr --help and grr schema are the source of truth, and every one of the 402 methods is a real, typed command.
| Group | What it covers | Methods |
|---|---|---|
grr auth |
login [--device] [--account name] [--service name] [--all-scopes], status [--account name], setup [--client-id] [--client-secret] [--print-only] [--force] [--enable-apis] — all accept -f json|jsonl|table|pretty; status reports the credential's own scope set under scopes_granted (what Google actually approved — login's scopes_requested is what was asked for) |
— |
grr ask |
"<request>" [--run] [--dry-run] [--service] [--method] — natural language to a typed method + params via a System One model; prints the plan by default |
- |
grr mcp |
an MCP (JSON-RPC over stdio) server exposing every method as a typed tool; speaks the stateless 2026-07-28 revision — server/discover for discovery, plus a minimal legacy initialize handshake so standard MCP clients connect; --readonly for read-only |
- |
grr api |
list [--service X] [--filter substr] [--grouped], describe <id>, call <id> …, refresh [--service X] — every method by id, the flat escape hatch |
402 |
grr schema |
the whole command tree as JSON | — |
grr completions |
<bash|elvish|powershell|zsh> — a shell completion script for the whole tree, offline; see Install |
— |
grr transport |
negotiated HTTP version + runtime features | — |
grr skills |
install [--dir PATH] [--claude] [--force], list — the 16 packaged skill files (the core skill, one per service, and their index) into the user-level skills directory (~/.agents/skills, offline; --claude mirrors to ~/.claude/skills) |
— |
grr gmail |
messages, threads, drafts, labels, history, attachments, filters, forwarding, POP/IMAP, send-as, CSE, delegates, watches | 79 |
grr calendar |
calendars, events, instances, ACL, free/busy, colors, settings | 38 |
grr drive |
files, permissions, comments, replies, revisions, changes, drives, apps, approvals | 64 |
grr people |
contacts, connections, contact groups, other contacts, directory people | 24 |
grr chat |
spaces, members, messages, reactions, media, custom emoji, read state | 55 |
grr forms |
form bodies, responses, watches, publish settings | 10 |
grr tasks |
tasklists and the tasks inside them | 14 |
grr docs |
documents get / create / batchUpdate |
3 |
grr sheets |
spreadsheets, values, batch operations, developer metadata | 17 |
grr slides |
presentations, pages, thumbnails | 5 |
grr script |
script projects, deployments, versions, processes, running functions | 16 |
grr analyticsadmin |
accounts, properties, data streams, custom dimensions and metrics, conversion events | 55 |
grr analyticsdata |
standard, realtime, pivot and batch reports, audience exports | 11 |
grr searchconsole |
search analytics queries, sitemaps, sites, URL inspection | 11 |
Safety profiles. --readonly, --deny-service <name> and --deny-verb <VERB> are global flags honored by the generated tree, grr api call, grr ask and grr mcp alike — they parse before or after the subcommand, and turn destructive methods into actionable errors:
grr --readonly gmail users messages delete --user-id me --id abc # refused: DELETE
grr --deny-service chat chat spaces list # refused: the chat service
The generated tree
Every service command above is generated from the committed index by scripts/generate-commands.ts — there are no hand-written per-service commands and no hand-written per-service clients. scripts/generate-commands.ts reads the committed Discovery index (src/discovery/*.json, ~2.6 MiB across the 14 services) and emits the whole tree into src/commands/generated.rs — 402 leaves, 996 typed flags, using clap's builder API. A daily workflow refetches Google's Discovery Service, regenerates the index along with the command tree, the per-service agent skills, and the site's coverage table, and opens a PR, so new API surface reaches you without waiting for a grr release. The tree and the index are generated artifacts: never hand-edit them.
The rules, so you can predict any command without memorizing it:
- The naming rule. A leaf mirrors its Discovery method id:
gmail.users.messages.list→grr gmail users messages list. Resources nest as subcommands; each leaf also carries its bare method name as a visible alias (list,get— camelCase methods keep their casing, e.g.getProfile). - Typed flags per method. Parameter names come from the same ids:
userId→--user-id,maxResults→--max-results. Integers are parsed asi64, booleans are presence flags, repeated parameters repeat (--label-ids a --label-ids b), enum parameters validate their values, and required parameters are enforced by clap. - The collision rule. A parameter named
format,query,params,body-file,dry-run, orhelpwould collide with the shared escape hatches, so it is exposed as--param-format/--param-query/ … (seeRESERVED_FLAG_IDSinscripts/script-utils.ts). - Untyped bodies. Discovery's request schemas are not part of the index, so
POST/PATCH/PUTbodies pass through--params <JSON>(merged; typed flags win) or--body-file <PATH|->verbatim. - Every leaf also carries the escape hatches:
--params <JSON>,--body-file, repeatable--query KEY=VALUE,--dry-run, and-f json|jsonl|table|pretty.
Dispatch resolves the leaf's id against the embedded index and funnels into one shared call path — the same engine grr api call uses. The two routes are interchangeable:
grr api call gmail.users.messages.list --param userId=me --dry-run
grr gmail users messages list --user-id me --dry-run
# byte-identical output
grr api stays as the flat escape hatch: list [--service] [--filter] [--grouped] to browse, describe <id> for parameters and scopes, call <id> to invoke, refresh [--service] to pull the index forward between releases. Because the index is embedded rather than fetched, both grr api list and grr schema work with no network at all.
Consent starts small: grr auth login requests Gmail, Drive, Calendar, Tasks, Docs, Sheets, Slides and the sign-in scopes, and grr auth login --service <name> adds one service's scopes from the embedded index (--all-scopes asks for the whole ~112-scope union). That default exists because Google's consent screen stops submitting past roughly 27 ticked boxes on an unverified project — with no error at all — so asking for everything makes a first-time login impossible. Every login carries include_granted_scopes, so widening merges with what the account already granted instead of replacing it. Chat's app-authentication scopes (chat.bot, chat.app.*, chat.import) are never requested: a user consent screen cannot show them, and one of them fails the whole authorization with invalid_scope. Everything the index can express stays reachable that way, so a call is never refused for want of a narrower sibling. grr api describe still reports each method's least-privilege scope for a human deciding what a call touches. A 403 therefore means a scope outside the current grant (the message names it — run grr auth login --service <name> for that service) or an API that is not enabled on your Cloud project. Every API behind a command (tasks.googleapis.com, docs.googleapis.com, sheets.googleapis.com, slides.googleapis.com) must still be enabled on your Cloud project — see docs/gcp-setup.md.
grr-cli MCP questions
Do I need to configure an OAuth client for release binaries?
No, release binaries are zero-config because an OAuth client is already compiled into the binary.
Can I use grr-cli on a headless machine?
Yes, using grr auth login --device will print a URL and code for authentication instead of attempting to open a browser.