·

Google Sheets MCP With Gemini CLI

Set up Google Sheets MCP in Gemini CLI so your AI agent can read and write spreadsheet data right from your editor.

Gemini CLI's native strength with structured data — Gemini models are trained on and tend to reason cleanly about tabular data — makes it a natural pairing for spreadsheet-heavy work, and Google's own ecosystem alignment (same vendor as Sheets itself) shows up in small but real ways, like cleaner handling of Google's API error messages. This topic covers setup, aggregation/pivot-style prompting, a full weekly-report example, and an honest comparison against Claude Code's output on the same task.

Installing and Connecting Google Sheets MCP to Gemini CLI

Gemini CLI reads MCP servers from .gemini/settings.json (project) or ~/.gemini/settings.json (user-level). Register the server under mcpServers:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@gongrzhe/server-gsheets-mcp"],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/Users/you/.config/google-sheets-mcp/credentials.json",
        "GOOGLE_TOKEN_PATH": "/Users/you/.config/google-sheets-mcp/token.json"
      },
      "trust": false
    }
  }
}

Setting "trust": false (the default) means Gemini CLI prompts for tool-call approval on each write call the first time it's invoked in a session — keep it that way for this MCP specifically, even if you've set trust: true elsewhere, since the cost of an approved-by-habit destructive write here is higher than for most other MCP servers in this course.

Confirm the connection:

gemini mcp list

This should show google-sheets as connected with its tool count. If it shows connected but with zero tools, Gemini CLI's most common cause (distinct from OpenCode's path issue) is a version mismatch between the CLI's MCP SDK support and the server's declared protocol version — update both to current releases before digging further:

npm install -g @google/gemini-cli@latest
npx -y @gongrzhe/server-gsheets-mcp@latest --version

As with the other clients, complete the OAuth consent flow by running the server binary standalone once before relying on Gemini CLI to trigger it — Gemini CLI's process management for MCP subprocesses doesn't always surface a spawned browser window cleanly in headless or remote-shell contexts (SSH sessions, containers), so doing it locally first avoids a confusing hang.

Tips
- Leave trust: false on the Google Sheets MCP entry specifically, regardless of your global trust settings for other servers — the per-call approval friction is worth it here.
- If tools show as zero despite a "connected" status, check CLI and server versions before assuming a config error — this is a known class of issue across MCP clients broadly, not specific to Gemini.
- Complete first-run OAuth consent in a local terminal with a real browser available, not over SSH — headless environments need the --no-browser / manual-code flow some servers support instead, which is slower to debug if you hit it unprepared.

Aggregating and Pivoting Spreadsheet Data from Gemini CLI

Gemini CLI is genuinely strong at pivot-style prompts — asking for a cross-tabulation in natural language and getting a correctly grouped, correctly summed table back without having to spell out the aggregation logic step by step.

Read 'Sales'!A1:F3000 from spreadsheet 1QwErTyUiOpAsDfGhJkLzXcVbNm.
Row 1 is header: date, region, product_category, rep_name, units, revenue.

Pivot this: rows = product_category, columns = region, values = sum(revenue).
Show me the pivot table.

Where this gets more interesting — and where Gemini CLI's handling is noticeably better than a generic prompt-and-hope approach — is nested aggregation:

Same data. Now give me, per region: total revenue, average revenue per
rep (revenue / distinct rep_name count), and the top-3 product_category
by revenue within that region. Present as one table per region.

For genuinely large pivots, it's worth explicitly directing Gemini toward code generation rather than in-context arithmetic, the same caveat as with any LLM doing math over hundreds of rows:

Write and run a short Python script (pandas) that reads the data you
already fetched, builds the pivot table (rows=product_category,
columns=region, values=sum of revenue), and prints it. Don't compute
the sums yourself in your response — use the script's output.

This matters more than it sounds: LLM-computed sums over dozens of rows are usually right, but confidence should drop fast past a few hundred rows summed purely "in the model's head" versus verified via executed code. Gemini CLI's code execution tool makes this an easy ask — use it any time the aggregate feeds a decision, not just a curiosity.

Tips
- For pivots with more than roughly 200–300 input rows, explicitly require a script-executed aggregation rather than trusting in-context arithmetic — this is standard practice regardless of model, not a Gemini-specific weakness.
- State the exact pivot shape (rows / columns / values / aggregation function) rather than "pivot this by region" — ambiguity here produces plausible-looking but wrong groupings.
- Ask for row counts per pivot cell alongside the aggregate value at least once per new report type, as a sanity check that the grouping key matched what you expected (catches silent category-name typos like "North America" vs "N. America" splitting a group in two).

Practical Example: Generating a Weekly Metrics Report from Raw Data

A full walkthrough, start to finish, of the kind of report this MCP is genuinely good for.

Source: a Raw-Events tab logging one row per user action (timestamp, user_id, event_type, plan_tier). Target: a Weekly-Report tab with signups, activations, and churn-risk flags for the past 7 days.

Step 1: Read Raw-Events!A2:D20000. Filter to timestamp within the last
7 days from today (2026-08-21, so from 2026-08-14).

Step 2: Compute:
- total_signups = count of event_type = "signup"
- total_activations = count of event_type = "activation"
- activation_rate = total_activations / total_signups
- churn_risk_count = count of distinct user_id with event_type =
  "downgrade" AND plan_tier was "paid" in the row immediately prior
  for that user_id

Show me all four numbers plus your row-count for the filtered dataset,
before writing anything.

Review the output — this is where you catch a filter-window bug (off-by-one day, timezone mismatch between the sheet's stored format and "today") before it becomes a wrong headline number in a report someone forwards to leadership. Then:

Step 3: Write a "Weekly-Report" tab (create if missing) with this layout:
A1: "Metric"   B1: "Value"
A2: "Total Signups (7d)"      B2: <total_signups>
A3: "Total Activations (7d)"  B3: <total_activations>
A4: "Activation Rate"         B4: <activation_rate as percentage, 1 decimal>
A5: "Churn Risk Count (7d)"   B5: <churn_risk_count>
A6: "Report Generated"        B6: <today's date>
Use valueInputOption RAW throughout.

Then close the loop with a narrative for distribution — this is the piece that turns a spreadsheet update into something a non-technical stakeholder actually reads:

Step 4: Write two sentences summarizing the week for a Slack post:
one on signup/activation trend versus the metric's typical range for
this sheet, one flagging the churn-risk number if it's above 5.
Show me the two sentences here; don't write them to the sheet.

Tips
- Always state the report's reference date explicitly in the prompt (don't rely on the agent's notion of "today" matching your intended reporting week) — this is the single most common source of an off-by-one-week report.
- Review computed headline numbers before the write step, every time, even for a report you've run before — the input data changes each week even if the logic doesn't.
- Keep the narrative-summary step separate from the sheet-write step; a summary meant for Slack doesn't belong hardcoded into a spreadsheet cell where it'll go stale next week.

Comparing Google Sheets MCP Output Between Gemini CLI and Claude Code

Run the same weekly-report prompt through both clients on the same underlying spreadsheet and a few real differences show up, worth knowing before you pick one as your default for this MCP.

Aggregation accuracy on natural-language pivot requests. Gemini CLI tends to get pivot shape right on the first attempt slightly more often when the prompt is loosely specified ("pivot by region and category") — likely a function of Gemini's general strength on structured/tabular reasoning. Claude Code catches up fully once the pivot shape is stated explicitly, so this gap mostly disappears with more precise prompting on either side.

Multi-step chain reliability. Claude Code holds more context across a long read-compute-write-summarize chain in one turn without needing the steps as separately confirmed messages, particularly for chains longer than three or four tool calls. Gemini CLI benefits more from the explicit step-by-step breakdown shown in this topic's examples — it's not unreliable, but it rewards more structure in the prompt.

Error message clarity on Sheets API failures. Gemini CLI surfaces raw Google API error bodies more directly in some configurations (useful for debugging a 403 or a malformed range), where Claude Code sometimes summarizes the error in its own words, occasionally losing the specific API error code you'd want for troubleshooting. When you're actively debugging an auth or range issue, this favors Gemini CLI as your diagnostic client even if you don't use it for the actual work.

Tool-approval friction. Gemini CLI's default trust: false behavior means more interactive approval clicks per session unless you deliberately configure trust — a real, if minor, productivity difference for high-frequency spreadsheet work, and a deliberate trade-off for safety that's worth keeping rather than turning off wholesale.

Neither client is categorically better here — pick based on which failure mode you'd rather guard against: Claude Code for long unattended chains, Gemini CLI for tighter approval gates and clearer raw API errors during setup and debugging.

Tips
- Use Gemini CLI as your go-to for initial setup and auth debugging on this MCP — its raw API error surfacing saves time diagnosing scope and range issues.
- For long, multi-step recurring reports, lean on whichever client you've validated holds context reliably for your specific chain length and complexity — don't assume either one generalizes from a short example to a ten-step pipeline.
- If your team standardizes on one client for spreadsheet work, document the choice and the reason in your project's MCP setup notes — the failure modes above are subtle enough that a new team member won't rediscover them without being told.

Tips

Gemini CLI's natural fit for tabular reasoning makes it a strong choice for ad hoc analysis and pivot-heavy prompts on Google Sheets MCP; keep its default approval friction rather than disabling it, and lean on its clearer raw API error output when you're debugging auth or range problems rather than fighting through a paraphrased error from elsewhere.

Tips
- Keep trust: false on this MCP server in Gemini CLI even after you trust the overall workflow — the failure cost here is asymmetric.
- Reach for script-executed aggregation, not in-context arithmetic, once a pivot input crosses a few hundred rows.
- When debugging a new spreadsheet connection or a permissions error, start in Gemini CLI for its clearer raw API error surfacing, then move the validated workflow to whichever client you'll actually run day to day.

Next Google Sheets MCP With Cursor