io.github.chrischall/gogcli-mcp-sheets

Authorize a Google account via browser-based OAuth. Opens a browser window where the user must sign in and grant access. Blocks for up to 5 minutes waiting for the user to complete authorization. If the browser does not open automatically, a fallback URL is included in the response. Use gog_auth_list to check which accounts are already configured.

Complete REMOTE/headless Google authorization (step 2 of 2). Takes the full redirected localhost URL the user copied after finishing gog_auth_add_url, exchanges it for a refresh token, and stores it. Use the SAME `services` value you passed to gog_auth_add_url. Must run within 10 minutes of step 1 and against the same gogcli host.

Begin REMOTE/headless Google authorization (step 1 of 2). Returns a sign-in URL to open in any browser — no local server or terminal on the gogcli host is needed, so this works on a hosted deployment where the interactive gog_auth_add cannot. Hand the URL to the user; after they sign in, the browser is redirected to a localhost URL that fails to load — that is expected. They copy that full redirected URL (from the address bar) and you pass it to gog_auth_add_complete. The link is valid for 10 minutes. If you pass a custom `services` here, pass the SAME value to gog_auth_add_complete or the second step will not match this one.

Check the LIVE health of each stored Google account. Unlike gog_auth_status (which only reports keyring/config setup), this performs a real token refresh against Google, so it detects expired or revoked (invalid_grant) refresh tokens — the account-wide sign-out that blocks every service. Reports per account: whether the token is currently valid, the mapped cause when it is not, how long ago it was authorized, and a warning as it approaches the 7-day refresh-token limit that applies to OAuth apps whose consent screen is still in "Testing" mode. Run it proactively to re-authorize on your own schedule instead of mid-task. On a hosted deployment this is the ONLY check that measures Google: a connector showing "connected" or "refreshed" has verified the client's connection to the MCP host, and nothing else — the Google credential lives in gog's keyring on that host and can be dead while the connection looks perfectly healthy.

List the Google accounts stored in gogcli, with their scopes. This reads local configuration only — it does not contact Google and does NOT tell you whether an account still works: a signed-out account whose refresh token expired or was revoked is listed here exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account can actually authenticate.

Run any gog auth subcommand not covered by the other tools. Run `gog auth --help` for the full list of subcommands, or `gog auth <subcommand> --help` for flags on a specific subcommand. Only these subcommands are available: list, status, services, alias. Flags that override server safety controls (--readonly, --enable-commands, --disable-commands, --account, --access-token, --home, --client, --gmail-no-send, --no-input) and a bare "--" are refused. Local file paths (--out, --out-dir, --attach, --file, --*-file, @file JSON) must be inside GOG_FILE_ROOTS; subcommands that take a local path positionally (e.g. drive upload) are refused in favour of their dedicated tools. For browser-based authorization, use gog_auth_add instead.

List all Google services supported by gogcli and the OAuth scopes each requires.

Show gogcli auth CONFIGURATION: keyring backend, credential files, and auth setup. Despite the name this is not a health check — it reads local setup and does not contact Google, so it says nothing about whether an account can still authenticate. Use gog_auth_health for that.

Add a new sheet tab to a spreadsheet.

Append rows to a Google Sheet after the last row with data in the given range. Values may be strings, numbers, booleans, or null. Strings starting with "=" are interpreted as formulas.

Remove alternating-color banding. Pass id to remove a single banded range, or all:true with sheet to remove every banding on that sheet.

List alternating-color banded ranges. Optionally scope to a single sheet.

Apply alternating colors to a range. Provide rowPropertiesJson and/or columnPropertiesJson — each a Sheets API BandingProperties JSON object ({headerColor, firstBandColor, secondBandColor, footerColor}). At least one is required.

Open a persisted, revision-locked Sheets request batch. Pass its returned batchId to gog_sheets_batch_request using batch=<id>; no spreadsheet changes are submitted until gog_sheets_batch_end.

Submit a persisted Sheets request batch atomically against its locked revision. The queued requests are shown for review and require confirmation before they are applied.

Submit a Google Sheets API structural request array atomically (for example addDimension, repeatCell, mergeCells, or updateSheetProperties). requestsJson must be a JSON array of Sheets API Request objects. Requests are previewed and require confirmation before submission. Use batch=<id> to append these requests to a persisted Sheets batch instead of submitting immediately.

Update values in multiple ranges with one Sheets API request. dataJson is a JSON array of {range, values} objects — pass it inline as a literal JSON string. Atomic — either all ranges update or none do. (The CLI also accepts "@/path/to/file.json", but that file is read on the gog server's filesystem, not the caller's, so inline JSON is the right form for remote MCP callers.)

Create an embedded chart from a JSON spec. specJson is a Sheets API ChartSpec (or full EmbeddedChart) — inline or @/path/to/file.json. Anchor the chart with sheet + anchor (A1 cell), and optionally size it with width/height pixels.

Delete a chart by its numeric chart ID.

Get the full definition (spec + position) of a single chart by its numeric chart ID.

List embedded charts in a spreadsheet (chartId, type, position).

Replace a chart spec by chart ID. specJson is a Sheets API ChartSpec (or full EmbeddedChart) — inline or @/path/to/file.json.

Clear all values in a Google Sheets range (formatting is preserved).

Add a conditional formatting rule to a range. Boolean rules: type picks the condition, expr is its value/formula (omit for blank/not-blank), formatJson is the CellFormat to apply when the condition matches (inline or @file); use formatFields to force-send zero/false fields (e.g. backgroundColor,textFormat.bold). Gradient rules (color scales): pass gradientRuleJson instead — a GradientRule JSON with minpoint/maxpoint (and optional midpoint), each {"color":{...},"type":"MIN|MAX|NUMBER|PERCENT|PERCENTILE","value":"..."}. The two modes are mutually exclusive.

Remove conditional formatting rules from a sheet. Pass index to remove a single rule by its 0-based index, or all:true to remove every rule on the sheet.

List conditional formatting rules. Optionally scope to a single sheet.

Copy a spreadsheet to a new spreadsheet with the given title.

Copy a source range's values/formulas/format to a destination range via the Sheets CopyPasteRequest. A destination larger than the source tiles the source to fill it — the canonical way to fill formulas down or across with relative references adjusted (aliases: fill, copy-range). Use type to control what is pasted (NORMAL pastes everything; FORMULA fills formulas with adjusted references; VALUES/FORMAT/etc. paste only that aspect).

Create a new Google Spreadsheet. Returns JSON with the new spreadsheetId and URL.

Add a BigQuery Connected Sheets data source to a spreadsheet, creating its linked DATA_SOURCE sheet. Point it at EITHER a custom SQL query (query) OR an existing native table (dataset + table) — never both. billingProject is the BigQuery project charged for the query; tableProject only names which project OWNS the table, and defaults to the billing project. Returns the new dataSourceId, which every other datasource tool takes. COSTS MONEY AND RUNS ASYNCHRONOUSLY: this starts a BigQuery execution billed to the billing project, and returns once the execution has been REQUESTED — not once it has finished. Poll gog_sheets_datasource_describe until its dataExecutionStatus state is SUCCEEDED or FAILED before treating the data as current. Because it bills, it first asks the MCP host to show the user a confirmation prompt naming the spreadsheet, the query or table and the billing project; nothing runs unless they accept. If the client cannot show that prompt (no MCP elicitation, e.g. claude.ai), a two-step flow applies instead: call WITHOUT confirmToken and nothing is sent or changed — the result has status "confirmation-required", the full preview and a confirmToken. Follow its instruction (by default: show the preview to the user verbatim and only after they explicitly approve it in chat, call again with the SAME arguments plus confirmToken). The tool re-reads what it would act on and refuses (DRAFT_CHANGED, with a fresh preview and token) if it changed; TOKEN_EXPIRED / TOKEN_REUSED / TOKEN_INVALID also do nothing. A server set to MCP_CONFIRM_MODE=refuse refuses instead. BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account's EXISTI…

Delete a Connected Sheets data source. This is WIDER than it sounds: it also deletes the source's linked DATA_SOURCE sheet, and unlinks every extract, chart and pivot table built on it elsewhere in the spreadsheet — objects on other tabs that the caller never named. Take gog_sheets_snapshot first if any of that matters. The BigQuery data itself is untouched; only the spreadsheet's connection to it goes away. BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account's EXISTING services selection and passing extraScopes=https://www.googleapis.com/auth/bigquery.readonly with forceConsent. Looker sources reuse the account's existing Looker link and need nothing extra.

Describe one Connected Sheets data source in full: the complete API DataSource spec (including the BigQuery raw query, which gog_sheets_datasource_list withholds), its sheet properties, its DataExecutionStatus and any refresh schedules. Refreshes are asynchronous and this tool cannot start one — poll it until state is SUCCEEDED or FAILED, and read the status error text when it is FAILED. BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account's EXISTING services selection and passing extraScopes=https://www.googleapis.com/auth/bigquery.readonly with forceConsent. Looker sources reuse the account's existing Looker link and need nothing extra.

List the Connected Sheets data sources in a spreadsheet (BigQuery or Looker), each joined with its DATA_SOURCE sheet and current execution status. This is the discovery call — start here to get the dataSourceId the describe tool wants. Deliberately does not print custom SQL; use gog_sheets_datasource_describe for that. BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account's EXISTING services selection and passing extraScopes=https://www.googleapis.com/auth/bigquery.readonly with forceConsent. Looker sources reuse the account's existing Looker link and need nothing extra.

Re-run a Connected Sheets data source so its sheet and extracts pick up current BigQuery data. Google refuses to refresh a source whose previous execution FAILED; forceRefresh overrides that, which is what you want after fixing the underlying query or permissions. COSTS MONEY AND RUNS ASYNCHRONOUSLY: this starts a BigQuery execution billed to the billing project, and returns once the execution has been REQUESTED — not once it has finished. Poll gog_sheets_datasource_describe until its dataExecutionStatus state is SUCCEEDED or FAILED before treating the data as current. Because it bills, it first asks the MCP host to show the user a confirmation prompt naming the spreadsheet, the query or table and the billing project; nothing runs unless they accept. If the client cannot show that prompt (no MCP elicitation, e.g. claude.ai), a two-step flow applies instead: call WITHOUT confirmToken and nothing is sent or changed — the result has status "confirmation-required", the full preview and a confirmToken. Follow its instruction (by default: show the preview to the user verbatim and only after they explicitly approve it in chat, call again with the SAME arguments plus confirmToken). The tool re-reads what it would act on and refuses (DRAFT_CHANGED, with a fresh preview and token) if it changed; TOKEN_EXPIRED / TOKEN_REUSED / TOKEN_INVALID also do nothing. A server set to MCP_CONFIRM_MODE=refuse refuses instead. BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account's EXISTING services selection and passing extraScopes=https://www.googleapis.com/auth/bigquery.readonly with forceConsent. Looker sources reuse the account's existing Looker…

Describe the data-source table (extract) anchored at an A1 cell: its source, configured columns, sort/filter spec and row limit. Read this before gog_sheets_datasource_table_read when you need to know what the columns MEAN — the read returns values, not the extract's definition. BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account's EXISTING services selection and passing extraScopes=https://www.googleapis.com/auth/bigquery.readonly with forceConsent. Looker sources reuse the account's existing Looker link and need nothing extra.

List the data-source tables — "extracts" in the Sheets editor — anchored in a spreadsheet. A data-source table has NO id of its own in the Sheets API: its definition lives on its top-left cell, so every extract is identified by a sheet-qualified A1 anchor (e.g. "Extracts!B3"). That anchor is what the describe and read tools take. Filter with dataSourceId to see only one source's extracts. BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account's EXISTING services selection and passing extraScopes=https://www.googleapis.com/auth/bigquery.readonly with forceConsent. Looker sources reuse the account's existing Looker link and need nothing extra.

Read the values out of the data-source table (extract) anchored at an A1 cell. Bounded on purpose: at most maxRows data rows (gog default 1000) plus the header row, which is returned separately. The JSON reports "truncated": true when the configured extract can hold more rows than were returned — treat that exactly like a truncated search, i.e. do not conclude a value is absent from it; raise maxRows or narrow the extract instead. Use render=UNFORMATTED_VALUE for arithmetic (FORMATTED_VALUE returns display strings) or render=FORMULA to see the cell formulas. BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with gog_auth_add_url/gog_auth_add_complete (or gog_auth_add), keeping the account's EXISTING services selection and passing extraScopes=https://www.googleapis.com/auth/bigquery.readonly with forceConsent. Looker sources reuse the account's existing Looker link and need nothing extra.

Repoint an existing BigQuery Connected Sheets data source: new SQL for a query-backed source, a new dataset/table for a table-backed one, or a new billing project for either. Only the fields you pass are changed. You cannot convert a source between the two kinds — gog refuses SQL on a table source and table fields on a query source — so read gog_sheets_datasource_describe first if you are unsure which kind it is. Replacing the SQL DISCARDS the source's current results. COSTS MONEY AND RUNS ASYNCHRONOUSLY: this starts a BigQuery execution billed to the billing project, and returns once the execution has been REQUESTED — not once it has finished. Poll gog_sheets_datasource_describe until its dataExecutionStatus state is SUCCEEDED or FAILED before treating the data as current. Because it bills, it first asks the MCP host to show the user a confirmation prompt naming the spreadsheet, the query or table and the billing project; nothing runs unless they accept. If the client cannot show that prompt (no MCP elicitation, e.g. claude.ai), a two-step flow applies instead: call WITHOUT confirmToken and nothing is sent or changed — the result has status "confirmation-required", the full preview and a confirmToken. Follow its instruction (by default: show the preview to the user verbatim and only after they explicitly approve it in chat, call again with the SAME arguments plus confirmToken). The tool re-reads what it would act on and refuses (DRAFT_CHANGED, with a fresh preview and token) if it changed; TOKEN_EXPIRED / TOKEN_REUSED / TOKEN_INVALID also do nothing. A server set to MCP_CONFIRM_MODE=refuse refuses instead. BIGQUERY-BACKED SOURCES NEED AN EXTRA SCOPE: ordinary sheets authorization does not request https://www.googleapis.com/auth/bigquery.readonly, and Google refuses the whole response without it. A permission error here means the token is missing that scope, NOT that the spreadsheet has no data sources — re-authorize with gog_auth_add_url/gog_auth_add_complete (or…

Delete a span of rows or columns, table-aware: intersecting table objects are preserved (shrunk) along with their remaining data, instead of being corrupted as with a raw DeleteDimension batch update. Target by A1 range (e.g. Sheet1!5:7 or Sheet1!C:D) or by sheet name plus start/end.

Delete a sheet tab from a spreadsheet.

Export a spreadsheet as CSV, TSV, or PDF.

Set a basic filter on a range (the filter/sort header Sheets shows on a data range). A sheet can hold one basic filter; replacing an existing one requires replace=true — without it, gog refuses rather than silently overwriting.

Find and replace text across an entire Google Spreadsheet.

Apply cell formatting to a range. The named flags (bold, italic, backgroundColor, etc.) compose into a Sheets API CellFormat — use them for the 90% case. For full API control, pass formatJson + formatFields (Sheets CellFormat + field mask) directly.

Freeze rows and/or columns in a sheet.

Read values from a Google Sheets range. Returns a JSON object with a "values" array of rows.

Insert rows or columns into a sheet. With after:false (default), the new dimension lands at start. With after:true, the new dimension lands at start+1 (the existing dimension at start is preserved).

List hyperlinks in a range.

Set cell hyperlinks in a Google Sheet. Three modes: (1) single link — pass cell + url (+ optional text); (2) multi-link cell — pass cell + runsJson, a JSON array of rich-text runs (a run with an empty uri is plain text); (3) batch — pass cellsJson, a JSON array of {cell,url,text} or {cell,runs:[...]} objects written in one request.

List tabs (sheets) in a spreadsheet with their titles, sheetIds, and indices. A friendlier view than gog_sheets_metadata when you only need the tab list — useful for restructuring a workbook over a long agent session without losing track of names.