> This page is for Workforce.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Google Sheets

**Authentication:** OAuth. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow, or [Application credentials](/merge-agent-handler/admin-setup/add-oauth-credentials) to bring your own OAuth app.

## Sample use cases

* Append today's Stripe payouts to the `Finance / Daily` sheet, deduped by transaction ID.
* Pull the values from the `Q2 Forecast` sheet and post the rollup in #finance.
* Find rows in the `Leads` sheet where the email domain matches our top 10 target accounts.

## Available Tools

#### add_sheet

Add a new sheet (tab) to an existing spreadsheet with customizable properties.

#### delete_sheet

Permanently delete a sheet (tab) from a spreadsheet. Cannot be undone.

#### update_sheet_properties

Update sheet properties like title, position, visibility, or tab color.

#### copy_sheet

Copy a sheet within the same spreadsheet or to a different spreadsheet.

#### sort_range

Sorts data in rows based on a sort order per column. Supports multi-column sorting and color-based sorting.

#### set_data_validation

Sets data validation rules to cells in a range. Supports number, text, date validation, dropdown lists, and custom rules. Use empty rule to clear validation.

#### set_basic_filter

Sets a basic filter on a sheet with optional sorting and column-specific filter criteria. Supports text, number, and date filtering.

#### add_chart

Add a chart (bar, line, area, column, scatter, combo, stepped area) to a spreadsheet. Requires A1 ranges for domain (x-axis) and series (y-axis) data.

#### create_spreadsheet

Create a new spreadsheet with specified title and optional properties.

#### get_spreadsheet

Retrieve spreadsheet information including metadata, sheets, and optionally cell data.

#### update_spreadsheet_properties

Update spreadsheet properties such as title, locale, or timezone.

#### get_values

Read cell values from a specified range using A1 notation (e.g., 'Sheet1!A1:B10').

#### update_values

Write cell values to a specified range. Supports formulas and raw values.

#### append_values

Append rows to the end of a table, automatically finding the last row with data.

#### clear_values

Clear cell values from a range while preserving formatting and structure.

#### batch_get_values

Read cell values from multiple ranges in a single efficient API call.

#### batch_update_values

Update multiple ranges with values in a single efficient API call.

#### batch_clear_values

Clear values from multiple ranges in a single API call while preserving formatting.

#### add_banding

Apply alternating row or column colors (zebra striping) to a range. range accepts A1 notation (e.g. 'Sheet1!A1:E20') or a GridRange object.

#### add_conditional_format_rule

Add a conditional formatting rule to one or more ranges. Provide either booleanRule (condition + format) or gradientRule (minpoint/midpoint/maxpoint),…

#### add_dimension_group

Create a collapsible row or column group for hierarchical reports. range.dimension is ROWS or COLUMNS; range.

#### add_filter_view

Create a named filter view with persistent filter/sort criteria. Unlike set_basic_filter, multiple filter views coexist without overwriting each other…

#### add_named_range

Create a named range so the cells can be referenced by name in formulas (e.g. =SUM(SalesData)). Names should be valid identifiers.

#### add_protected_range

Lock a range from edits. warning_only=True shows a warning but still allows edits; False blocks them.

#### auto_fill

Extend a pattern (formula, date sequence, number series) by auto-fill instead of writing each value.

#### auto_resize_dimensions

Auto-fit row heights or column widths to content. dimensions.dimension is ROWS or COLUMNS; start_index/end_index are zero-based, end-exclusive.

#### delete_banding

Delete a banding rule by ID. Use get_spreadsheet to find banded_range_id values on each sheet. This is irreversible.

#### delete_conditional_format_rule

Delete a conditional format rule at the given 0-based index on a sheet. To inspect existing rules use get_spreadsheet with include_grid_data=True.

#### delete_dimension

Delete rows or columns from a sheet. range.dimension is ROWS or COLUMNS; range.start_index/end_index are zero-based, end-exclusive.

#### delete_duplicates

Remove duplicate rows from a range, comparing only the columns listed in comparison_columns (DimensionRange list). The first occurrence is kept.

#### delete_embedded_object

Delete an embedded chart or image by its id. The object_id is the chart_id returned by add_chart, or read from get_spreadsheet (sheets\[].charts\[].

#### delete_filter_view

Delete a named filter view by ID. Use get_spreadsheet to find filter_view_id values on each sheet. This is irreversible.

#### delete_named_range

Delete a named range by ID. Use get_spreadsheet to find named_range_id values. Formulas referencing the deleted name will break. This is irreversible.

#### duplicate_sheet

Duplicate a sheet within the same spreadsheet using DuplicateSheetRequest. Unlike copy_sheet (which uses :copyTo and auto-names the result), this lets…

#### find_replace

Bulk find and replace text. Provide exactly one scope: a range (GridRange), a sheet_id, or all_sheets=True.

#### format_cells

Apply cell-level formatting (number format, colors, fonts, alignment, wrap, borders, padding) to a range using RepeatCellRequest.

#### insert_dimension

Insert empty rows or columns into a sheet. range.dimension selects ROWS or COLUMNS; range.start_index/end_index are zero-based, end-exclusive.

#### merge_cells

Merge cells across a range. Discards content from all cells except the top-left of each merged block; not reversible via unmerge_cells.

#### move_dimension

Reorder rows or columns. source.dimension is ROWS or COLUMNS; source.start_index/end_index are zero-based, end-exclusive.

#### trim_whitespace

Strip leading and trailing whitespace from string cells in a range. Returns the count of cells changed. Common cleanup after data import.

#### unmerge_cells

Unmerge previously merged cells in a range. Useful for decomposing merged template cells before editing.

#### update_banding

Update an existing banding rule's range or colors. Provide banded_range_id (from add_banding or get_spreadsheet) and the fields to change.

#### update_borders

Set borders around a cell range. Each side (top/bottom/left/right) takes a Border with style and optional colorStyle.

#### update_chart

Update an existing chart's spec — change chart type, title, or data ranges. Provide chart_id (from add_chart) and the spec fields to change.

#### update_conditional_format_rule

Replace a conditional format rule at a given index, or move it to a new position. sheet_id targets the sheet; index is the rule's current 0-based posi…

#### update_dimension_properties

Set column widths or row heights, or hide/show dimensions. range.dimension is ROWS or COLUMNS; range.

#### update_embedded_object_position

Reposition an embedded object (chart or image) by id. Use new_sheet_id to move to another sheet, or overlay fields to set anchor cell, pixel offsets,…

#### update_filter_view

Update an existing named filter view. Provide filter_view_id (from add_filter_view or get_spreadsheet) plus the fields to change.

#### update_named_range

Update an existing named range's name or cell range. Provide the named_range_id (from add_named_range or get_spreadsheet); pass name and/or range to c…

#### add_table

Add a table to a sheet over a GridRange (include the header row). Optionally set per-column names and types