Google Sheets Import and Export

v1.0.2$0.01/block of 100 rowsData Extraction

Last updated November 20, 2026

Read a Google Sheet into an Apify dataset, or write an Apify dataset or a list of rows into a Google Sheet: append, replace, or update rows by a key column. Works on your own Google service account or OAuth token; a sheet shared as anyone with the link reads with no credential.

Install

bash
npx @mambalabsdev/mcp-google-sheets-import-export

Every tool here also runs hosted, with no install at all, through Apify's MCP endpoint.

Features

  • Read any tab into JSON rows keyed by its header row; a sheet shared as anyone with the link needs no credential.
  • Write an Apify dataset or a list of rows: append, replace the tab, or upsert by a key column.
  • New columns are added to the header as they appear; values are written as plain text unless you ask for formulas.
  • Billed per block of up to 100 rows; empty, refused, and failed writes are free.
  • Pay per event: Rows written, per block of up to 100 at $0.01.

Input

modestringoptional

read (default): the sheet becomes one dataset row per sheet row. append: add rows after the last row. replace: clear the tab, then write the rows. upsert: overwrite the rows whose key_column value is already in the sheet and add the rest. The three write modes need a credential below.

spreadsheetstringoptional

The Google Sheets URL as copied from the browser, or the spreadsheet ID. A #gid= in the URL picks that tab.

sheetstringoptional

Optional. The tab name, or its gid number. Default: the gid in the URL, else the first tab. In a write mode a tab name that does not exist is created.

rangestringoptional

Optional, read mode. An A1 range without the tab name, for example A1:F500 or B:D. Default: the whole tab.

header_rowstringoptional

true (default) or false. When true, read rows are keyed by the header row, and writes match your row keys to the header columns and add new columns at the end. When false, read rows are keyed by column letter and writes go column by column in key order.

dataset_idstringoptional

Write modes. The Apify dataset whose items go into the sheet, for example the default dataset of another run. In an Apify integration, pass the triggering run's resource.defaultDatasetId variable. Fields starting with # are skipped.

rowsarrayoptional

Write modes, instead of a dataset. A JSON list of objects, one per sheet row, for example [{"name": "Ann", "email": "ann@example.com"}].

columnsarrayoptional

Optional, write modes. Only these keys are written, in this order. Default: every key in the rows, in first seen order.

key_columnstringoptional

Upsert mode. The column whose value identifies a row, for example email or url. A row whose value is already in that column is overwritten in place; the rest are added. Rows with no value in it are skipped.

value_inputstringoptional

raw (default): every value is stored exactly as given, so text starting with = is not run as a formula. user_entered: Google parses values as if typed, so formulas run and dates and numbers are converted.

max_rowsstringoptional

Most rows to read or write in this run, 1 to 1,000,000 (default 100,000).

service_account_jsonstringoptional

Your own service account key file, pasted whole. Share the spreadsheet with its client_email as an Editor (Viewer to read). It is sent only to Google and is never stored, logged, or written to a row.

oauth_refresh_tokenstringoptional

Instead of a service account: a refresh token from your own Google OAuth client with the spreadsheets scope. Needs oauth_client_id and oauth_client_secret from the same client.

oauth_client_idstringoptional

The client ID that issued the refresh token.

oauth_client_secretstringoptional

The client secret that issued the refresh token.

oauth_access_tokenstringoptional

Instead of the above: a current OAuth access token with the spreadsheets scope. It expires in about an hour, so it suits a single run.

max_charge_usdstringoptional

Optional. The run stops before a charge that would pass this amount, and never writes a block of rows it could not charge. Summary rows are always returned.

Output schema

json
{
  "row_type": "string",
  "spreadsheet_id": "string",
  "sheet": "string",
  "mode": "string",
  "access": "string",
  "row_number": "integer",
  "values": "object",
  "cells": "array",
  "rows_in_block": "integer",
  "range": "string",
  "rows_read": "integer",
  "rows_written": "integer",
  "rows_updated": "integer",
  "rows_appended": "integer",
  "row_status": "string",
  "error_reason": "string",
  "billable_events_json": "string",
  "scraped_at": "string"
}

Pricing

$0.01per block of 100 rows
EventFree plan price
Rows written, per block of up to 100$0.01
Rows read, per block of up to 100$0.005
Actor Start$0.002

Pay per event on the Apify platform. Paid Apify plans pay less per event. No subscription, no seat license.

On the Apify free plan the actor stops at $1.50 of charges a month, about 150 block of 100 rowss. Any paid Apify plan removes the cap.

Limits

  • Read mode returns the cell text as shown in the sheet (formatted values), not the formulas.
  • A public read by tab name uses Google's gviz export. It can return empty cells in a column that mixes numbers and text, it leaves out rows hidden by a filter left on the tab, and a tab name that does not exist returns the first tab instead of an error. Read by gid (the number after #gid= in the URL) to avoid all three; that uses the CSV export. Reads with a credential use the Sheets API and do not have these limits.
  • Upsert matches on exact text after trimming spaces. Rows with no value in key_column are skipped and counted on the summary row. Inside one write, the last row with a given key wins.
  • Objects and lists in your rows are written as JSON text. A cell holds at most 50,000 characters; longer values are cut, and the summary row counts them.
  • Replace clears the whole tab, formatting kept, values removed.
  • The Google Sheets API allows 60 write requests a minute per user by default. The actor writes up to 500 rows per request and waits when Google asks it to.
  • An OAuth access token expires in about an hour. For runs longer than that, use a service account key or a refresh token.