# Google Sheets — how to use (mcp.ai)

Read, create and update Google Sheets spreadsheets straight from your AI agent.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_googlesheets?ms=1781045700000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `googlesheets_list`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/googlesheets`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/googlesheets/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/googlesheets/add/sheet` — Adds a new sheet (worksheet) to a spreadsheet. use this tool to create a new tab within an existing google sheet, optionally specifying its title, index, size, and other properties.
  - body: { properties?: object, spreadsheetId: string, responseIncludeGridData?: boolean, includeSpreadsheetInResponse?: boolean }
- `POST https://api.mcp.ai/api/googlesheets/aggregate/column/data` — Searches for rows where a specific column matches a value and performs mathematical operations on data from another column.
  - body: { operation: string, sheet_name: string, search_value: string, search_column: string, target_column: string, case_sensitive?: boolean, has_header_row?: boolean, spreadsheet_id: string, percentage_total?: number }
- `POST https://api.mcp.ai/api/googlesheets/append/dimension` — Tool to append new rows or columns to a sheet, increasing its size. use when you need to add empty rows or columns to an existing sheet.
  - body: { length: integer, sheet_id: integer, dimension: string, spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/batch/get` — Retrieves data from specified cell ranges in a google spreadsheet; ensure the spreadsheet has at least one worksheet and any explicitly referenced sheet names in ranges exist.
  - body: { ranges?: string[], spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/batch/update` — Updates a specified range in a google sheet with given values, or appends them as new rows if `first cell location` is omitted; ensure the target sheet exists and the spreadsheet contains at least one
  - body: { values: array[], sheet_name: string, spreadsheet_id: string, valueInputOption?: string, first_cell_location?: string, includeValuesInResponse?: boolean }
- `POST https://api.mcp.ai/api/googlesheets/batch/update/values/by/data/filter` — Tool to update values in ranges matching data filters. use when you need to update specific data in a google sheet based on criteria rather than fixed cell ranges.
  - body: { data: object[], spreadsheetId: string, valueInputOption: string, includeValuesInResponse?: boolean, responseValueRenderOption?: string, responseDateTimeRenderOption?: string }
- `POST https://api.mcp.ai/api/googlesheets/clear/basic/filter` — Tool to clear the basic filter from a sheet. use when you need to remove an existing basic filter from a specific sheet within a google spreadsheet.
  - body: { sheet_id: integer, spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/clear/values` — Clears cell content (preserving formatting and notes) from a specified a1 notation range in a google spreadsheet; the range must correspond to an existing sheet and cells.
  - body: { range: string, spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/create/chart` — Create a chart in a google sheets spreadsheet using the specified data range and chart type.
  - body: { title?: string, sheet_id?: integer, subtitle?: string, chart_type: string, data_range: string, x_axis_title?: string, y_axis_title?: string, background_red?: number, spreadsheet_id: string, background_blue?: number, legend_position?: string, background_green?: number }
- `POST https://api.mcp.ai/api/googlesheets/create/google/sheet1` — Creates a new google spreadsheet in google drive using the provided title.
  - body: { title: string }
- `POST https://api.mcp.ai/api/googlesheets/create/spreadsheet/column` — Creates a new column in a google spreadsheet, requiring a valid `spreadsheet id` and an existing `sheet id`; an out-of-bounds `insert index` may append/prepend the column.
  - body: { sheet_id: integer, insert_index?: integer, spreadsheet_id: string, inherit_from_before?: boolean }
- `POST https://api.mcp.ai/api/googlesheets/create/spreadsheet/row` — Inserts a new, empty row into a specified sheet of a google spreadsheet at a given index, optionally inheriting formatting from the row above.
  - body: { sheet_id: integer, insert_index?: integer, spreadsheet_id: string, inherit_from_before?: boolean }
- `POST https://api.mcp.ai/api/googlesheets/delete/dimension` — Tool to delete specified rows or columns from a sheet in a google spreadsheet. use when you need to remove a range of rows or columns.
  - body: { spreadsheet_id: string, response_ranges?: string[], delete_dimension_request: object, response_include_grid_data?: boolean, include_spreadsheet_in_response?: boolean }
- `POST https://api.mcp.ai/api/googlesheets/delete/sheet` — Tool to delete a sheet (worksheet) from a spreadsheet. use when you need to remove a specific sheet from a google sheet document.
  - body: { sheet_id: integer, spreadsheetId: string }
- `POST https://api.mcp.ai/api/googlesheets/execute/sql` — Execute sql queries against google sheets tables. supports select, insert, update, and delete operations with familiar sql syntax. tables are automatically detected and mapped from the spreadsheet str
  - body: { sql: string, dry_run?: boolean, delete_method?: string, spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/find/worksheet/by/title` — Finds a worksheet by its exact, case-sensitive title within a google spreadsheet; returns a boolean indicating if found and the complete metadata of the entire spreadsheet, regardless of whether the t
  - body: { title: string, spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/format/cell` — Applies text and background cell formatting to a specified range in a google sheets worksheet.
  - body: { red?: number, blue?: number, bold?: boolean, green?: number, italic?: boolean, fontSize?: integer, underline?: boolean, worksheet_id: integer, end_row_index: integer, strikethrough?: boolean, spreadsheet_id: string, start_row_index: integer, end_column_index: integer, start_column_index: integer }
- `POST https://api.mcp.ai/api/googlesheets/get/sheet/names` — Lists all worksheet names from a specified google spreadsheet (which must exist), useful for discovering sheets before further operations.
  - body: { spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/get/spreadsheet/by/data/filter` — Returns the spreadsheet at the given id, filtered by the specified data filters. use this tool when you need to retrieve specific subsets of data from a google sheet based on criteria like a1 notation
  - body: { dataFilters: object[], spreadsheetId: string, includeGridData?: boolean, excludeTablesInBandedRanges?: boolean }
- `POST https://api.mcp.ai/api/googlesheets/get/spreadsheet/info` — Retrieves comprehensive metadata for a google spreadsheet using its id, excluding cell data.
  - body: { spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/get/table/schema` — This action is used to get the schema of a table in a google spreadsheet, call this action to get the schema of a table in a spreadsheet before you query the table. analyze table structure and infer c
  - body: { sheet_name?: string, table_name: string, sample_size?: integer, spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/insert/dimension` — Tool to insert new rows or columns into a sheet at a specified location. use when you need to add empty rows or columns within an existing google sheet.
  - body: { spreadsheet_id: string, response_ranges?: string[], insert_dimension: object, response_include_grid_data?: boolean, include_spreadsheet_in_response?: boolean }
- `POST https://api.mcp.ai/api/googlesheets/list/tables` — This action is used to list all tables in a google spreadsheet, call this action to get the list of tables in a spreadsheet. discover all tables in a google spreadsheet by analyzing sheet structure an
  - body: { min_rows?: integer, min_columns?: integer, min_confidence?: number, spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/lookup/spreadsheet/row` — Finds the first row in a google spreadsheet where a cell's entire content exactly matches the query string, searching within a specified a1 notation range or the first sheet by default.
  - body: { query: string, range?: string, case_sensitive?: boolean, spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/query/table` — This action is used to query a table in a google spreadsheet, call this action to query a table in a spreadsheet. execute sql-like select queries against spreadsheet tables. supports where conditions,
  - body: { sql: string, spreadsheet_id: string, include_formulas?: boolean }
- `POST https://api.mcp.ai/api/googlesheets/search/developer/metadata` — Tool to search for developer metadata in a spreadsheet. use when you need to find specific metadata entries based on filters.
  - body: { dataFilters: object[], spreadsheetId: string }
- `POST https://api.mcp.ai/api/googlesheets/search/spreadsheets` — Search for google spreadsheets using various filters including name, content, date ranges, and more.
  - body: { query?: string, order_by?: string, max_results?: integer, starred_only?: boolean, created_after?: string, modified_after?: string, shared_with_me?: boolean, include_trashed?: boolean }
- `POST https://api.mcp.ai/api/googlesheets/set/basic/filter` — Tool to set a basic filter on a sheet in a google spreadsheet. use when you need to filter or sort data within a specific range on a sheet.
  - body: { filter: object, spreadsheetId: string }
- `POST https://api.mcp.ai/api/googlesheets/sheet/from/json` — Creates a new google spreadsheet and populates its first worksheet from `sheet json`, which must be non-empty as its first item's keys establish the headers.
  - body: { title: string, sheet_json: object[], sheet_name: string }
- `POST https://api.mcp.ai/api/googlesheets/spreadsheets/sheets/copy/to` — Tool to copy a single sheet from a spreadsheet to another spreadsheet. use when you need to duplicate a sheet into a different spreadsheet.
  - body: { sheet_id: integer, spreadsheet_id: string, destination_spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/spreadsheets/values/append` — Tool to append values to a spreadsheet. use when you need to add new data to the end of an existing table in a google sheet.
  - body: { range: string, values: array[], spreadsheetId: string, majorDimension?: string, insertDataOption?: string, valueInputOption: string, includeValuesInResponse?: boolean, responseValueRenderOption?: string, responseDateTimeRenderOption?: string }
- `POST https://api.mcp.ai/api/googlesheets/spreadsheets/values/batch/clear` — Tool to clear one or more ranges of values from a spreadsheet. use when you need to remove data from specific cells or ranges while keeping formatting and other properties intact.
  - body: { ranges: string[], spreadsheet_id: string }
- `POST https://api.mcp.ai/api/googlesheets/spreadsheets/values/batch/clear/by/data/filter` — Clears one or more ranges of values from a spreadsheet using data filters. the caller must specify the spreadsheet id and one or more datafilters. ranges matching any of the specified data filters wil
  - body: { dataFilters: object[], spreadsheetId: string }
- `POST https://api.mcp.ai/api/googlesheets/spreadsheets/values/batch/get/by/data/filter` — Tool to return one or more ranges of values from a spreadsheet that match the specified data filters. use when you need to retrieve specific data sets based on filtering criteria rather than entire sh
  - body: { dataFilters: object[], spreadsheetId: string, majorDimension?: string, valueRenderOption?: string, dateTimeRenderOption?: string }
- `POST https://api.mcp.ai/api/googlesheets/update/sheet/properties` — Tool to update properties of a sheet (worksheet) within a google spreadsheet, such as its title, index, visibility, tab color, or grid properties. use this when you need to modify the metadata or appe
  - body: { spreadsheetId: string, updateSheetProperties: object }
- `POST https://api.mcp.ai/api/googlesheets/update/spreadsheet/properties` — Tool to update properties of a spreadsheet, such as its title, locale, or auto-recalculation settings. use when you need to modify the overall configuration of a google sheet.
  - body: { fields: string, properties: object, spreadsheetId: string }

## More
- Page: https://mcp.ai/googlesheets
- Agent spec (llms.txt): https://mcp.ai/googlesheets/llms.txt
- Postman collection: https://mcp.ai/googlesheets/postman.json