Google Sheets Spreadsheets
Use a Google Sheet as a lightweight database: list the tabs of a spreadsheet, read one or many ranges, append new rows, overwrite cells, and create new spreadsheets. Based on the Google Sheets API specification.
Connect this API to an AI agent Browse all specs
What you can do with Google Sheets Spreadsheets via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v4/spreadsheets/{spreadsheetId} |
getSpreadsheet | Get a spreadsheet's title and tabs (pass fields=properties,sheets.properties) |
| GET | /v4/spreadsheets/{spreadsheetId}/values/{range} |
getValues | Read the cell values in one range, e.g. 'Sheet1'!A1:D20 |
| PUT | /v4/spreadsheets/{spreadsheetId}/values/{range} |
updateValues | Overwrite the cells in one range |
| GET | /v4/spreadsheets/{spreadsheetId}/values:batchGet |
batchGetValues | Read several ranges in one call |
| POST | /v4/spreadsheets/{spreadsheetId}/values/{range}:append |
appendValues | Add new rows after the last row of a table |
| POST | /v4/spreadsheets/{spreadsheetId}/values:batchUpdate |
batchUpdateValues | Overwrite cells in several ranges in one call |
| POST | /v4/spreadsheets |
createSpreadsheet | Create a new spreadsheet with a title and tabs |
Authentication
googleOAuth
OAuth 2.0
Scopes: https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets
Google OAuth 2.0 (authorization code flow) on behalf of the signed-in user.
How to get a credential
- In the Google Cloud Console (https://console.cloud.google.com) create or pick a project and enable the Google Sheets API (APIs & Services > Library).
- Configure the OAuth consent screen (Google Auth Platform > Branding / Audience) and add the scopes below under Data Access. While the app is in Testing, add your users as test users.
- Create an OAuth client ID of type Web application and add the VX Agents redirect URI shown in the credential dialog as an authorized redirect URI.
- Paste the client ID and client secret into the VX Agents credential and connect your Google account; request offline access so the token can refresh.
Permissions used
| Scope | Operations |
|---|---|
https://www.googleapis.com/auth/spreadsheets.readonly |
getSpreadsheet, getValues, batchGetValues |
https://www.googleapis.com/auth/spreadsheets |
createSpreadsheet, updateValues, appendValues, batchUpdateValues (also allows reading) |
Common errors
- 401 Unauthorized: the access token expired or was revoked; reconnect the account or refresh the token.
- 403 Forbidden:
PERMISSION_DENIED= the spreadsheet is not shared with the connected account, or the token only has the read-only scope;SERVICE_DISABLED= enable the Sheets API in the Cloud project. - 400 Bad Request:
Unable to parse range= bad A1 notation or a tab name that does not exist (quote names with spaces:'Q3 Sales'!A1:D). - 404 Not Found: wrong spreadsheetId (it is the long id in the sheet URL between /d/ and /edit).
- 429 Too Many Requests: per-minute quota exceeded (about 60 requests per user per minute); wait and retry, and prefer batchGetValues / batchUpdateValues.
Store the connected Google account as a VX Agents credential for this spec; never paste tokens into chat.
Usage guide
Setup
- Credential: connect a Google account with OAuth (spreadsheets.readonly to read, spreadsheets to write). The sheet must be shared with that account.
- Preset
spreadsheetIdif the agent always works on one sheet: it is the long id in the URLdocs.google.com/spreadsheets/d/<spreadsheetId>/edit. - Preset
valueInputOption=USER_ENTEREDon write tools so dates, numbers and formulas are parsed like typed input.
Read and add rows
- getSpreadsheet with
fields=properties.title,sheets.propertiesto list the tab names and sizes (never fetch the whole grid with includeGridData). - getValues on the header row first (
'Sheet1'!1:1) to learn the columns, then read the data range ('Sheet1'!A2:F). Use batchGetValues with severalrangesto read multiple tabs at once. - To add records, appendValues with
range='Sheet1'!A1,valueInputOption=USER_ENTERED,insertDataOption=INSERT_ROWSand body{values: [[...row 1...], [...row 2...]]}in header-column order. - To change existing cells, find the row number from the data you read, show the user the exact range and new values, and only after they confirm call updateValues (one range) or batchUpdateValues (
data: [{range, values}]). These overwrite whatever is there. - createSpreadsheet with
properties.titleand optionalsheets[].properties.titlemakes a new file in the user's Drive; then write the header row with updateValues.
Good to know
- A1 notation: quote tab names with spaces or symbols (
'Q3 Sales'!A1:D20);A:A= a whole column,2:2= a whole row. - Values come back as rows of strings by default; empty trailing cells are omitted, so rows can be shorter than the header. Use
valueRenderOption=UNFORMATTED_VALUEfor raw numbers anddateTimeRenderOption=FORMATTED_STRINGfor readable dates. majorDimension=COLUMNSreturns column arrays instead of rows.- Quota is about 60 read and 60 write requests per minute per user: batch reads and writes.
- Clearing ranges, deleting tabs and formatting changes are intentionally not available.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Google Sheets Spreadsheets” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.