Google Sheets

Performs Google Sheets operations - create, read, update, and format spreadsheets, worksheets, rows, and cells.

MCP Tool Pack Available

Want to expose Google Sheets actions as MCP tools for AI assistants? Use the Google Sheets MCP Tool Pack to deploy all 28 tools in one step - no manual configuration needed.

Configuration

Field	Type	Default	Description
Service Account JSON	secret	-	Google service account credentials JSON (required)
Delegate To	string	-	Email to impersonate via Domain-Wide Delegation
Action	select	-	The spreadsheet operation to perform (required)
Spreadsheet ID	string	-	The ID of the target spreadsheet (required for most actions)
Sheet Name	string	-	Name of the worksheet/sheet tab
New Sheet Name	string	-	New name when renaming a worksheet
Range	string	-	Cell range in A1 notation (e.g. A1:D10)
Row Index	integer	-	Row number for single-row operations
Start Row	integer	-	Starting row for range operations
End Row	integer	-	Ending row for range operations
Values	string	-	JSON array of values for row/cell operations
Column Name	string	-	Column header name for lookup or create operations
Lookup Value	string	-	Value to search for in lookup operations
Lookup Column	string	-	Column to search in for lookup operations
Sort Column	string	-	Column to sort by
Sort Order	string	ascending	Sort direction: ascending or descending
Title	string	-	Spreadsheet or worksheet title
Destination Spreadsheet ID	string	-	Target spreadsheet for copy operations
Format	string	-	JSON formatting object for format actions
Validation Rule	string	-	JSON data validation rule
Condition Format Rule	string	-	JSON conditional formatting rule
Max Results	integer	100	Maximum number of rows to return

Authentication

This processor supports two authentication methods: OAuth Connection (recommended for personal accounts) and Service Account (for server-to-server automation).

Option A: OAuth Connection (recommended)

OAuth lets you authorize Qaynaq to act as your Google account. Data is owned by you, using your quota. You authorize once and it works indefinitely.

Follow the Google OAuth Setup guide to create a connection. Make sure to enable the Google Sheets API and add the auth/spreadsheets scope. Then select your connection from the OAuth Connection dropdown in the processor configuration.

Option B: Service Account

Service accounts are best for Google Workspace organizations with Domain-Wide Delegation.

Step 1: Create a Service Account

1. Go to the Google Cloud Console
2. Create a project or select an existing one
3. Navigate to IAM & Admin > Service Accounts
4. Click Create Service Account, give it a name, and click Done
5. Click the service account, go to the Keys tab
6. Click Add Key > Create new key > JSON
7. Download the JSON key file

Step 2: Enable the Google Sheets API

1. In Google Cloud Console, go to APIs & Services > Library
2. Search for Google Sheets API and click Enable

Step 3: Store the Credentials

1. Open the downloaded JSON key file and copy its entire contents
2. In Qaynaq, go to Settings > Secrets
3. Create a new secret (e.g. key: GOOGLE_SHEETS_SA) and paste the JSON as the value
4. In the Google Sheets processor, select GOOGLE_SHEETS_SA from the Service Account JSON dropdown

Step 4: Share Your Spreadsheet with the Service Account

A service account cannot access any spreadsheet by default. You must explicitly share each spreadsheet with the service account's email address:

1. Open the JSON key file and find the client_email field (e.g. my-service@my-project.iam.gserviceaccount.com)
2. Open your Google Spreadsheet and click Share
3. Paste the service account email and grant Editor access
4. Click Send (you can uncheck "Notify people" since it's a service account)

warning

Without this step, all operations will fail with a permission error. The service account can only read and write spreadsheets that have been shared with it.

Domain-Wide Delegation (Google Workspace only)

As an alternative to sharing individual spreadsheets, Google Workspace administrators can grant the service account access to all users' spreadsheets via Domain-Wide Delegation:

1. In Google Cloud Console, go to the service account details
2. Enable Domain-Wide Delegation and note the Client ID
3. In Google Workspace Admin Console, go to Security > API Controls > Domain-wide Delegation
4. Add the Client ID with the scope https://www.googleapis.com/auth/spreadsheets
5. Set the Delegate To field to the email of the user whose spreadsheets you want to access

Actions

Spreadsheet Management

Create Spreadsheet

Creates a new Google Sheets spreadsheet with a title and optional initial worksheet name.

Get Spreadsheet by ID

Retrieves spreadsheet metadata and properties by its ID.

Worksheet Management

Create Worksheet

Adds a new sheet tab to an existing spreadsheet.

Find Worksheet

Finds a worksheet by name within a spreadsheet.

Find or Create Worksheet

Finds a worksheet by name, or creates it if it does not exist.

Delete Worksheet

Removes a sheet tab from a spreadsheet.

Rename Worksheet

Changes the name of an existing sheet tab.

Copy Worksheet

Copies a worksheet to the same or another spreadsheet.

Change Sheet Properties

Updates sheet-level properties such as grid size, tab color, or frozen rows and columns.

Row Operations

Create Row

Appends a new row at the bottom of the sheet.

Create Multiple Rows

Appends multiple rows at the bottom of the sheet in a single request.

Create Row at Top

Inserts a new row at the top of the sheet, below the header row.

Get Row

Retrieves a single row by its row index.

Get Many Rows

Retrieves multiple rows from a range.

Get Data Range

Returns the full data range of the sheet, including header row and all populated rows.

Lookup Row

Finds the first row where a specified column matches a given value.

Lookup Rows

Finds all rows where a specified column matches a given value.

Update Row

Updates a single row at the specified row index.

Update Rows

Updates multiple rows in a specified range.

Clear Rows

Clears the content of rows in a specified range without deleting them.

Delete Rows

Permanently removes rows from the sheet.

Create Column

Adds a new column header to the sheet.

Formatting & Advanced

Copy Range

Copies a range of cells to a new location within the same or another spreadsheet.

Sort Range

Sorts a range of rows by a specified column in ascending or descending order.

Format Cells

Applies formatting (bold, color, borders, number format, etc.) to a range of cells.

Format Row

Applies formatting to an entire row.

Set Data Validation

Sets data validation rules on a range (e.g. dropdown lists, number ranges, custom formulas).

Create Conditional Formatting

Creates a conditional formatting rule that highlights cells based on their values or a custom formula.

Dynamic Fields

All action parameter fields support Bento interpolation functions, allowing dynamic values from message content using ${!this.field_name} syntax. This enables processing batches of spreadsheet operations or reacting to upstream data. For example, setting Spreadsheet ID to ${!this.spreadsheet_id} will read the spreadsheet ID from the incoming message.

JSON fields (Values, Format, Validation Rule, Condition Format Rule) also support interpolation. For example, set Values to ${!this.row_data} to pass through a JSON array from the message.

Static fields (not interpolated): Service Account JSON, Delegate To, Action, Max Results.

Output Format

All actions return a structured JSON object:

• Spreadsheet actions return a spreadsheet object containing the spreadsheet metadata (id, title, sheets, etc.)
• Worksheet actions return a sheet object with the sheet properties (sheetId, title, index, gridProperties)
• Row actions (get_row, lookup_row) return a row object with column-value pairs
• List actions (get_many_rows, lookup_rows, get_data_range) return a rows array and a count field
• Mutating actions (create_row, update_row, clear_rows, delete_rows) return confirmation with affected range information
• find_or_create_worksheet includes a created boolean field

tip

Use a Mapping processor after Google Sheets to extract specific fields from the response, such as cell values or the spreadsheet ID.