Google Sheets MCP Server

An MCP-style tool server that lets AI assistants (and any caller) read, write, and manage Google Sheets via the Google Sheets API v4. It exposes 14 tools covering cell/range read & write, append, sheet-tab management, formulas, JSON export, and batch operations.

This Actor is a thin, real wrapper around the official google-api-python-client. Every tool call makes a live request to the Google Sheets API using your credentials and input — there is no mock or sample data.

Key features

• 🧰 14 real tools — read/write cells & ranges, append rows, create/delete tabs, get/set formulas, export to JSON, and batch read+write in one call.
• 🔗 Live Google Sheets API v4 — every call hits the official API with your credentials; no mock or sample data.
• 🔐 Two auth modes — a service-account JSON key for full read/write, or an API key for read-only access to public sheets.
• 📦 Batch operations — combine multiple reads and writes in a single sheets_batch_update call.
• 🛡️ Never crashes on bad input — invalid credentials, an inaccessible sheet, or a malformed call return a structured success: false error, not a failed run.
• 🔌 Two ways to connect — run it in Standby mode to serve MCP over Streamable-HTTP for live MCP clients, or start a normal run with toolCall/toolCalls for one-shot batch execution that pushes results to the dataset.
• 🔄 Automation-ready — schedule it or call it from the Apify API to keep a sheet in sync with external data.

Use cases

• Give an AI agent a spreadsheet — let Claude/Cursor (via the Apify API or an integration) read and update a Google Sheet as part of a workflow.
• Automated data logging — append rows to a Sheet on a schedule (form responses, scrape results, metrics) for a live dashboard.
• Pull sheet data into a pipeline — export a tab to JSON and feed it to another actor, a model, or a BI tool.
• Programmatic sheet management — create/clear tabs, set formulas, and reformat ranges without opening the UI.
• Two-way sync — batch-read source ranges and batch-write computed results back in a single run.

What it does

You give the Actor:

1. Credentials — a Google service account JSON key (full read/write) or a Google API key (read-only).
2. A target spreadsheet — by spreadsheetId or full spreadsheetUrl.
3. One or more tool calls — toolCall (single) and/or toolCalls (array).

The Actor authenticates, loads the spreadsheet, runs each tool against the live API, and pushes one dataset record per result.

How to connect (two modes)

This Actor runs in either of two modes:

1. Standby (MCP over HTTP) — When the Actor is started in Standby mode, it serves the Model Context Protocol over Streamable-HTTP and stays running. MCP clients connect to the Standby URL and speak JSON-RPC 2.0:
   • initialize → returns protocol version 2024-11-05 and server info.
   • tools/list → returns the 14 tools (name + description).
   • tools/call → runs a tool and returns its JSON result in the MCP content field (with isError set when the tool reports success: false).
   • A GET on the Standby URL returns a small JSON summary (name, version, transport, tool names); OPTIONS is handled for CORS.
   • The target spreadsheet and credentials are taken from the Actor input at launch. In this mode results are returned as MCP tool responses, not pushed to the dataset.
2. Batch run (request/response) — When started normally (not Standby), the Actor authenticates, loads the spreadsheet, runs any toolCall/toolCalls you provided, pushes the results to the dataset, and exits.

Authentication

Parameter	Access level	Notes
credentialsJson	Full read/write	Google service account JSON key. Accepts the raw JSON string or a base64-encoded copy of it. Required for any write/append/create/delete/clear/formula-set operation.
apiKey	Read-only	Google API key. Can only read public spreadsheets (or those shared appropriately). Write tools will return a permission error from Google.

If both are supplied, credentialsJson is used first.

The Actor never crashes on missing or invalid credentials. If credentials are absent or malformed, it returns a clear, structured error and exits cleanly.

Input

Field	Type	Required	Description
credentialsJson	string (secret)	one auth method required	Service account JSON key (raw or base64).
apiKey	string (secret)	one auth method required	Google API key (read-only).
spreadsheetId	string	yes (or spreadsheetUrl)	Spreadsheet ID, the part of the URL between /d/ and /edit.
spreadsheetUrl	string	optional	Full Sheets URL; the ID is extracted automatically. Used only if spreadsheetId is not set.
toolCall	object	optional	A single tool to run: { "name": <tool>, "arguments": { ... } }.
toolCalls	array	optional	A list of { "name", "arguments" } objects, run in order.

Example input

{
  "credentialsJson": "{ ...service account JSON... }",
  "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
  "toolCall": {
    "name": "sheets_read_range",
    "arguments": {
      "range": "Sheet1!A1:D10",
      "include_headers": true
    }
  }
}

Tools (14) and their arguments

Tool	Arguments	Auth needed
sheets_read_cell	cell (str, e.g. "A1" or "Sheet1!B2"), value_render (str, default "FORMATTED_VALUE")	read
sheets_read_range	range (str), value_render (str), include_headers (bool), max_rows (int)	read
sheets_write_cell	cell (str), value (any)	write
sheets_write_range	range (str), data (2D array)	write
sheets_append_rows	sheet (str, tab name), data (2D array)	write
sheets_list_sheets	—	read
sheets_create_sheet	title (str), rows (int, default 1000), cols (int, default 26)	write
sheets_delete_sheet	title (str)	write
sheets_clear_range	range (str)	write
sheets_get_formula	cell (str)	read
sheets_set_formula	cell (str), formula (str; leading = optional)	write
sheets_to_json	sheet (str, default "Sheet1"), max_rows (int)	read
sheets_info	—	none (works without auth; richer when connected)
sheets_batch_update	reads (list of range strings), writes (list of {range, data})	read / write

value_render accepts the Google Sheets values:FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA.

Output

In batch run mode the Actor pushes records to the default dataset. (In Standby/MCP mode results are returned as MCP tool responses over HTTP and are not written to the dataset.) The dataset records are:

1. mcp_server_info — server name/version, the tool catalog, whether auth and the spreadsheet succeeded, and a capabilities map.
2. tool_result (one per tool call) — { "type": "tool_result", "tool": <name>, "arguments": {...}, "result": {...} }.
3. session_stats — counts of operations, reads, writes, and errors.

Each tool's result includes success: true|false. On failure it includes an error string (and the tool name) instead of throwing.

Example output (for the input above)

{
  "type": "tool_result",
  "tool": "sheets_read_range",
  "arguments": { "range": "Sheet1!A1:D10", "include_headers": true },
  "result": {
    "success": true,
    "range": "Sheet1!A1:D10",
    "row_count": 9,
    "headers": ["Name", "Email", "Age", "City"],
    "data": [["Alice", "a@x.com", "30", "NYC"], "..."],
    "records": [{ "Name": "Alice", "Email": "a@x.com", "Age": "30", "City": "NYC" }, "..."]
  }
}

Setup (service account)

1. Create a Google Cloud project.
2. Enable the Google Sheets API for that project.
3. Create a service account and download its JSON key.
4. Share your spreadsheet with the service account's email (found as client_email in the key) — give Editor access for writes.
5. Paste the JSON key into credentialsJson (raw or base64).

For read-only access to a public sheet, you can instead supply an apiKey.

Limitations

• Auth scope: the server requests only the https://www.googleapis.com/auth/spreadsheets scope. It operates on an existing spreadsheet you supply by spreadsheetId/spreadsheetUrl — it has no Drive scope, so it cannot create, list, or delete spreadsheet files (sheets_create_sheet creates a new tab inside the current spreadsheet, not a new spreadsheet).
• One spreadsheet per run/session: the target spreadsheet is fixed at launch from the input; individual tools do not take a spreadsheetId, so a single run/Standby session works against one spreadsheet only.
• API key auth is read-only and only works on sheets the key can access (typically public ones); write/append/create/delete/formula-set tools will return a Google permission error.
• The service account must be explicitly shared on each private spreadsheet (Editor access for writes); otherwise reads/writes fail with an access error.
• Reads and writes use Google's standard value semantics (USER_ENTERED for writes, so strings like =A1+B1 become formulas and "5" becomes a number).
• sheets_delete_sheet refuses to delete the last remaining sheet tab.
• Subject to Google Sheets API quotas and rate limits on your Google Cloud project.
• No interactive OAuth flow — authentication is unattended via a service account key or an API key only.

Errors and reliability

Invalid JSON credentials, a missing/garbled service-account key, an inaccessible spreadsheet, a malformed toolCall, or wrong tool arguments all produce a structured success: false error rather than crashing the run. This keeps the Actor healthy on Apify even when input is incomplete.

FAQ

Do I need a Google account? Yes — you need either a Google service account (for read/write) or a Google API key (read-only). Both are free to create in Google Cloud. See "Setup" above.

Why a service account instead of signing in with OAuth? A service account lets the Actor run unattended (scheduled, headless) without an interactive login. You simply share the target spreadsheet with the service account's email.

Is my data or credentials exposed? Credentials are passed as secret inputs and used only to call Google's API for your run. There's no mock layer — the Actor talks directly to your spreadsheet and returns exactly what Google returns.

Read-only vs. read/write — which do I need? Use an apiKey for read-only access to public sheets. Use a credentialsJson service-account key (shared on the sheet with Editor access) for any write, append, create, delete, or formula-set operation.

Can it run on a schedule? Yes. Pair it with an Apify Schedule to append rows or sync data on a recurring basis.

What about Google's rate limits? Calls count against your Google Cloud project's Sheets API quota. For heavy use, batch with sheets_batch_update and stagger scheduled runs.

Can it work across multiple spreadsheets? Each run targets one spreadsheet (spreadsheetId/spreadsheetUrl). Run it once per sheet — for example via several scheduled tasks — to cover more than one.