MCP Reference: sheetsmcp.googleapis.com

This is an MCP server which provides tools to interact with Google Sheets.

A Model Context Protocol (MCP) server acts as a proxy between an external service that provides context, data, or capabilities to a Large Language Model (LLM) or AI application. MCP servers connect AI applications to external systems such as databases and web services, translating their responses into a format that the AI application can understand.

MCP Tools

An MCP tool is a function or executable capability that an MCP server exposes to a LLM or AI application to perform an action in the real world.

Tools

The sheetsmcp.googleapis.com MCP server has the following tools:

MCP Tools
get_values

Returns a range of values from a spreadsheet.

Corresponds to spreadsheets.values.get in the REST API: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get

Schema: - spreadsheet_id (string, required): The ID of the spreadsheet to retrieve data from. - range (string, required): The A1 notation or R1C1 notation of the range to retrieve values from (e.g. "Sheet1!A1:B10").
get_spreadsheet

Returns the spreadsheet content for the given spreadsheet. Returns titles, sheet names, grid properties, and other metadata for the given spreadsheet ID. Also returns full grid data if requested.

Corresponds to spreadsheets.get in the REST API: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/get

Schema: - spreadsheet_id (string, required): The ID of the spreadsheet to request. - include_grid_data (boolean, optional): True if grid data should be returned. Defaults to false. - fields (array of strings, optional): Field masks specifying which properties to return (e.g. ["sheets.properties.sheetId", "sheets.properties.title"]). - comments_included (boolean, optional): If true, comments will be included in the response. Defaults to false. - ranges (array of strings, optional): The A1 or R1C1 ranges to retrieve from the spreadsheet. If not specified, the entire spreadsheet is returned.
update_spreadsheet

Applies one or more updates to the spreadsheet.

Corresponds to spreadsheets.batchUpdate in the REST API: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate

The list of possible updates is:

  • updateSpreadsheetProperties: Updates the spreadsheet's properties. Schema:
  • properties (object, required): Spreadsheet properties to update ({"title": string, "locale": string, "timeZone": string}).
  • fields (string, required): Field mask of properties to update (e.g. "title" or "*").
  • updateSheetProperties: Updates a sheet's properties. Schema:
  • properties (object, required): Sheet properties ({"sheetId": int, "title": string, "index": int, "gridProperties": {"rowCount": int, "columnCount": int, "frozenRowCount": int, "frozenColumnCount": int, "hideGridlines": bool}, "hidden": bool, "tabColorStyle": {"rgbColor": {"red": float, "green": float, "blue": float}}}).
  • fields (string, required): Field mask of properties to update (e.g. "title", "gridProperties.frozenRowCount").
  • updateDimensionProperties: Updates dimensions' properties (e.g. row height or column width). Schema:
  • range (object, required): Dimension range ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • properties (object, required): Dimension properties ({"pixelSize": int, "hiddenByUser": bool}).
  • fields (string, required): Field mask of properties to update (e.g. "pixelSize").
  • updateNamedRange: Updates a named range. Schema:
  • namedRange (object, required): Named range definition ({"namedRangeId": string, "name": string, "range": {"sheetId": int, "startRowIndex": int, "endRowIndex": int, "startColumnIndex": int, "endColumnIndex": int}}).
  • fields (string, required): Field mask of fields to update (e.g. "name,range" or "*").
  • repeatCell: Repeats a single cell across a range. Schema:
  • range (object, required): Grid range to apply cell data/formatting to ({"sheetId": int, "startRowIndex": int, "endRowIndex": int, "startColumnIndex": int, "endColumnIndex": int}).
  • cell (object, required): Cell data ({"userEnteredValue": {"stringValue": str, "numberValue": float, "formulaValue": str}, "userEnteredFormat": {"textFormat": {"bold": bool, "italic": bool, "fontSize": int}, "backgroundColorStyle": {"rgbColor": {"red": float, "green": float, "blue": float}}, "horizontalAlignment": "LEFT"|"CENTER"|"RIGHT", "wrapStrategy": "WRAP"|"CLIP"|"OVERFLOW_CELL"}}).
  • fields (string, required): Field mask of cell fields to update (e.g. "userEnteredFormat.textFormat.bold" or "userEnteredValue").
  • addNamedRange: Adds a named range. Schema:
  • namedRange (object, required): Named range to add ({"namedRangeId": string (optional), "name": string, "range": {"sheetId": int, "startRowIndex": int, "endRowIndex": int, "startColumnIndex": int, "endColumnIndex": int}}).
  • deleteNamedRange: Deletes a named range by its ID. Schema:
  • namedRangeId (string, required): ID of the named range to delete.
  • addSheet: Adds a sheet. Schema:
  • properties (object, optional): Sheet properties ({"title": string, "sheetId": int (optional), "index": int (optional), "gridProperties": {"rowCount": int, "columnCount": int}}).
  • deleteSheet: Deletes a sheet. Schema:
  • sheetId (integer, required): ID of the sheet to delete.
  • autoFill: Automatically fills in more data based on existing data. Schema:
  • range (object, optional): Range to examine and fill into ({"sheetId": int, "startRowIndex": int, "endRowIndex": int, "startColumnIndex": int, "endColumnIndex": int}).
  • sourceAndDestination (object, optional): Explicit source and fill length ({"source": GridRange, "dimension": "ROWS"|"COLUMNS", "fillLength": int}).
  • useAlternateSeries (boolean, optional): Whether to use alternate series.
  • cutPaste: Cuts data from one area and pastes it to another. Schema:
  • source (object, required): Source grid range.
  • destination (object, required): Top-left destination coordinate ({"sheetId": int, "rowIndex": int, "columnIndex": int}).
  • pasteType (string, optional): "PASTE_NORMAL", "PASTE_VALUES", "PASTE_FORMAT", "PASTE_NO_BORDERS", "PASTE_FORMULA".
  • copyPaste: Copies data from one area and pastes it to another. Schema:
  • source (object, required): Source grid range.
  • destination (object, required): Destination grid range.
  • pasteType (string, optional): "PASTE_NORMAL", "PASTE_VALUES", "PASTE_FORMAT", "PASTE_NO_BORDERS", "PASTE_FORMULA".
  • pasteOrientation (string, optional): "NORMAL" or "TRANSPOSE".
  • mergeCells: Merges cells together. Schema:
  • range (object, required): Grid range to merge.
  • mergeType (string, required): "MERGE_ALL", "MERGE_COLUMNS", or "MERGE_ROWS".
  • unmergeCells: Unmerges merged cells. Schema:
  • range (object, required): Grid range within which to unmerge all cells.
  • updateBorders: Updates the borders in a range of cells. Schema:
  • range (object, required): Grid range to update borders for.
  • top / bottom / left / right / innerHorizontal / innerVertical (object, optional): Border style ({"style": "SOLID"|"DASHED"|"DOTTED"|"DOUBLE"|"NONE", "width": int, "colorStyle": {"rgbColor": {"red": float, "green": float, "blue": float}}}).
  • updateCells: Updates many cells at once. Schema:
  • Area (exactly one required):
    • start (object): Top-left coordinate ({"sheetId": int, "rowIndex": int, "columnIndex": int}).
    • range (object): Grid range.
  • rows (array of RowData, required): Rows of cells ([{"values": [{"userEnteredValue": {"stringValue": str, "numberValue": float, "formulaValue": str}}]}]).
  • fields (string, required): Field mask of cell fields to update (e.g. "userEnteredValue" or "userEnteredFormat").
  • addFilterView: Adds a filter view. Schema:
  • filter (object, required): Filter view definition ({"title": string, "range": GridRange, "criteria": map, "sortSpecs": list}).
  • appendCells: Appends cells after the last row with data in a sheet. Schema:
  • sheetId (integer, required): Sheet ID to append data to.
  • rows (array of RowData, required): Rows of data to append.
  • fields (string, required): Field mask (e.g. "userEnteredValue").
  • clearBasicFilter: Clears the basic filter on a sheet. Schema:
  • sheetId (integer, required): Sheet ID on which to clear the basic filter.
  • deleteDimension: Deletes rows or columns in a sheet. Schema:
  • range (object, required): Dimension range to delete ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • deleteEmbeddedObject: Deletes an embedded object (e.g. chart, image) in a sheet. Schema:
  • objectId (integer, required): ID of the embedded object to delete.
  • deleteFilterView: Deletes a filter view from a sheet. Schema:
  • filterId (integer, required): ID of the filter view to delete.
  • duplicateFilterView: Duplicates a filter view. Schema:
  • filterId (integer, required): ID of the filter view to duplicate.
  • duplicateSheet: Duplicates a sheet. Schema:
  • sourceSheetId (integer, required): Sheet ID to duplicate.
  • insertSheetIndex (integer, optional): Zero-based index where the new sheet should be inserted.
  • newSheetId (integer, optional): ID for the new sheet.
  • newSheetName (string, optional): Name of the new sheet.
  • findReplace: Finds and replaces occurrences of some text with other text. Schema:
  • find (string, required): Value to search for.
  • replacement (string, required): Replacement value.
  • Scope (exactly one required):
    • range (object): Grid range.
    • sheetId (integer): Sheet ID.
    • allSheets (boolean): true to search all sheets.
  • matchCase / matchEntireCell / searchByRegex / includeFormulas (boolean, optional).
  • insertDimension: Inserts new rows or columns in a sheet. Schema:
  • range (object, required): Dimension range to insert ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • inheritFromBefore (boolean, optional): true to inherit formatting from preceding row/column.
  • insertRange: Inserts new cells in a sheet, shifting the existing cells. Schema:
  • range (object, required): Grid range to insert cells into.
  • shiftDimension (string, required): "ROWS" or "COLUMNS".
  • moveDimension: Moves rows or columns to another location in a sheet. Schema:
  • source (object, required): Source dimension range ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • destinationIndex (integer, required): Zero-based destination index.
  • updateEmbeddedObjectPosition: Updates an embedded object's (e.g. chart, image) position. Schema:
  • objectId (integer, required): ID of the embedded object.
  • newPosition (object, required): New position ({"overlayPosition": {"anchorCell": {"sheetId": int, "rowIndex": int, "columnIndex": int}, "widthPixels": int, "heightPixels": int}}).
  • fields (string, required): Field mask (e.g. "overlayPosition.anchorCell").
  • pasteData: Pastes data (HTML or delimited) into a sheet. Schema:
  • coordinate (object, required): Top-left coordinate ({"sheetId": int, "rowIndex": int, "columnIndex": int}).
  • data (string, required): Delimited text or HTML data.
  • delimiter (string, optional) or html (boolean, optional).
  • type (string, optional): "PASTE_NORMAL", "PASTE_VALUES", etc.
  • textToColumns: Converts a column of text into many columns of text. Schema:
  • source (object, required): Single-column grid range.
  • delimiterType (string, required): "COMMA", "SEMICOLON", "PERIOD", "SPACE", "CUSTOM", "AUTODETECT".
  • delimiter (string, optional): Delimiter character when delimiterType is "CUSTOM".
  • updateFilterView: Updates the properties of a filter view. Schema:
  • filter (object, required): Filter view definition including filterViewId.
  • fields (string, required): Field mask (e.g. "title,criteria" or "*").
  • deleteRange: Deletes a range of cells from a sheet, shifting the remaining cells. Schema:
  • range (object, required): Grid range to delete.
  • shiftDimension (string, required): "ROWS" or "COLUMNS".
  • appendDimension: Appends dimensions to the end of a sheet. Schema:
  • sheetId (integer, required): Sheet ID.
  • dimension (string, required): "ROWS" or "COLUMNS".
  • length (integer, required): Number of rows or columns to append.
  • addConditionalFormatRule: Adds a new conditional format rule. Schema:
  • rule (object, required): Conditional format rule ({"ranges": [GridRange], "booleanRule": {"condition": {"type": "NUMBER_GREATER_THAN_EQ"|"TEXT_CONTAINS"|..., "values": [{"userEnteredValue": string}]}, "format": CellFormat}, "gradientRule": {...}}).
  • index (integer, optional): Zero-based index where rule should be inserted.
  • updateConditionalFormatRule: Updates an existing conditional format rule. Schema:
  • rule (object, required): New conditional format rule.
  • Index / Rule ID (one required):
    • index (integer): Zero-based index of the rule.
    • sheetId (integer): Sheet ID if updating by sheet index.
  • newIndex (integer, optional): New index for moving the rule.
  • deleteConditionalFormatRule: Deletes an existing conditional format rule. Schema:
  • index (integer, required): Zero-based index of the rule to delete.
  • sheetId (integer, required): Sheet ID of the rule.
  • sortRange: Sorts data in a range. Schema:
  • range (object, required): Grid range to sort.
  • sortSpecs (array of SortSpec, required): Sort specifications ([{"dimensionIndex": int, "sortOrder": "ASCENDING"|"DESCENDING"}]).
  • setDataValidation: Sets data validation for one or more cells. Schema:
  • range (object, required): Grid range.
  • rule (object, optional): Validation rule ({"condition": {"type": "ONE_OF_LIST"|"NUMBER_BETWEEN"|..., "values": [{"userEnteredValue": string}]}, "strict": bool, "showCustomUi": bool}). If omitted, clears validation.
  • setBasicFilter: Sets the basic filter on a sheet. Schema:
  • filter (object, required): Basic filter definition ({"range": GridRange, "criteria": map, "sortSpecs": list}).
  • addProtectedRange: Adds a protected range. Schema:
  • protectedRange (object, required): Protected range definition ({"range": GridRange, "description": string, "warningOnly": bool, "editors": {"users": [string]}}).
  • updateProtectedRange: Updates a protected range. Schema:
  • protectedRange (object, required): Protected range definition with protectedRangeId.
  • fields (string, required): Field mask (e.g. "description,warningOnly" or "*").
  • deleteProtectedRange: Deletes a protected range. Schema:
  • protectedRangeId (integer, required): ID of protected range to delete.
  • autoResizeDimensions: Automatically resizes one or more dimensions based on cell contents. Schema:
  • dimensions (object, required): Dimension range ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • addChart: Adds a chart. Schema:
  • chart (object, required): Chart definition ({"spec": {"title": string, "basicChart": {"chartType": "COLUMN"|"BAR"|"LINE"|"PIE"|"COMBO"|"SCATTER", "legendPosition": string, "axis": list, "domains": list, "series": list}}, "position": {"overlayPosition": {"anchorCell": {"sheetId": int, "rowIndex": int, "columnIndex": int}}}}).
  • updateChartSpec: Updates a chart's specifications. Schema:
  • chartId (integer, required): ID of the chart.
  • spec (object, required): New chart specification.
  • updateBanding: Updates a banded range. Schema:
  • bandedRange (object, required): Banded range definition with bandedRangeId.
  • fields (string, required): Field mask.
  • addBanding: Adds a new banded range. Schema:
  • bandedRange (object, required): Banded range definition ({"range": GridRange, "rowProperties": {"headerColorStyle": ColorStyle, "firstBandColorStyle": ColorStyle, "secondBandColorStyle": ColorStyle}}).
  • deleteBanding: Removes a banded range. Schema:
  • bandedRangeId (integer, required): ID of banded range to delete.
  • createDeveloperMetadata: Creates new developer metadata. Schema:
  • developerMetadata (object, required): Metadata definition ({"metadataKey": string, "metadataValue": string, "location": {"locationType": "ROW"|"COLUMN"|"SHEET"|"SPREADSHEET", "sheetId": int}, "visibility": "DOCUMENT"|"PROJECT"}).
  • updateDeveloperMetadata: Updates an existing developer metadata entry. Schema:
  • dataFilters (array of DataFilter, required): Filters to select metadata.
  • developerMetadata (object, required): Updated metadata values.
  • fields (string, required): Field mask.
  • deleteDeveloperMetadata: Deletes developer metadata. Schema:
  • dataFilter (object, required): Filter describing criteria for metadata to delete.
  • randomizeRange: Randomizes the order of the rows in a range. Schema:
  • range (object, required): Grid range to randomize.
  • addDimensionGroup: Creates a group over the specified range. Schema:
  • range (object, required): Dimension range to group ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • deleteDimensionGroup: Deletes a group over the specified range. Schema:
  • range (object, required): Dimension range of group to delete.
  • updateDimensionGroup: Updates the state of the specified group. Schema:
  • dimensionGroup (object, required): Group definition ({"range": DimensionRange, "depth": int, "collapsed": bool}).
  • fields (string, required): Field mask (e.g. "collapsed").
  • trimWhitespace: Trims cells of whitespace (such as spaces, tabs, or new lines). Schema:
  • range (object, required): Grid range whose cells to trim.
  • deleteDuplicates: Removes rows containing duplicate values in specified columns of a cell range. Schema:
  • range (object, required): Grid range to remove duplicates from.
  • comparisonColumns (array of DimensionRange, optional): Specific columns to analyze.
  • updateEmbeddedObjectBorder: Updates an embedded object's border. Schema:
  • objectId (integer, required): ID of embedded object.
  • border (object, required): Border definition ({"colorStyle": ColorStyle, "section": "ALL"}).
  • fields (string, required): Field mask.
  • addSlicer: Adds a slicer. Schema:
  • slicer (object, required): Slicer definition ({"spec": {"dataRange": GridRange, "columnIndex": int, "title": string}, "position": {"overlayPosition": {"anchorCell": {"sheetId": int, "rowIndex": int, "columnIndex": int}}}}).
  • updateSlicerSpec: Updates a slicer's specifications. Schema:
  • slicerId (integer, required): ID of slicer.
  • spec (object, required): New slicer specification.
  • fields (string, required): Field mask.
  • addDataSource: Adds a data source. Schema:
  • dataSource (object, required): Data source definition ({"spec": {"bigQuery": {"projectId": string, "query": string}}}).
  • updateDataSource: Updates a data source. Schema:
  • dataSource (object, required): Data source definition with dataSourceId.
  • fields (string, required): Field mask.
  • deleteDataSource: Deletes a data source. Schema:
  • dataSourceId (string, required): ID of data source to delete.
  • refreshDataSource: Refreshes one or multiple data sources and associated dbobjects. Schema:
  • dataSourceId (string, optional) or isAll (boolean, optional) or references (object, optional).
  • force (boolean, optional): Whether to force refresh.
  • cancelDataSourceRefresh: Cancels refreshes of one or multiple data sources and associated dbobjects. Schema:
  • dataSourceId (string, optional) or isAll (boolean, optional) or references (object, optional).
  • addTable: Adds a table. Schema:
  • table (object, required): Table definition ({"range": GridRange, "name": string, "hasHeaderRow": bool, "hasTotalsRow": bool}).
  • updateTable: Updates a table. Schema:
  • table (object, required): Table definition with tableId.
  • fields (string, required): Field mask.
  • deleteTable: A request for deleting a table. Schema:
  • tableId (string, required): ID of table to delete.
  • insertComment: Inserts a comment into the spreadsheet. Schema:
  • content (string, required): Plain text comment content.
  • coordinate (object, required): Grid coordinate in the sheet to anchor the comment:
    • sheetId (integer, required): The sheet ID.
    • rowIndex (integer, required): Zero-based row index.
    • columnIndex (integer, required): Zero-based column index.
  • assigneeEmailAddress (string, optional): Email address of the assignee of the comment.
  • addCommentReply: Adds a reply to an existing comment thread. Also used to resolve or reopen a thread. Schema:
  • commentId (string, required): ID of the comment thread.
  • post (object, required):
    • content (string, required unless commentAction is RESOLVE or REOPEN): Plain text content of the reply post.
    • commentAction (string, optional): Action taken with this reply ("RESOLVE" or "REOPEN").
    • assigneeEmail (string, optional): Email address to newly assign the thread to.
  • updateCommentPost: Updates the content of a comment post in a comment thread. Schema:
  • commentId (string, required): ID of the comment thread.
  • postId (string, required): ID of the comment post to update.
  • content (string, required): The updated content of the comment post.
  • deleteComment: Deletes a comment thread. Schema:
  • commentId (string, required): ID of the comment thread to delete.
  • deleteCommentReply: Deletes a reply post. Schema:
  • commentId (string, required): ID of the comment thread.
  • postId (string, required): ID of the reply post to delete.
update_values

Sets values in a range of a spreadsheet.

Corresponds to spreadsheets.values.update in the REST API: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/update

Schema: - spreadsheet_id (string, required): The ID of the spreadsheet to update. - range (string, required): The A1 notation of the values to update (e.g. "Sheet1!A1:B2"). - values (array of arrays, required): 2D array of cell values. Supported value types are: boolean, string, and number (float/int).
update_formulas

Sets formulas in a range of a spreadsheet.

Corresponds to spreadsheets.values.update in the REST API: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/update

Schema: - spreadsheet_id (string, required): The ID of the spreadsheet to update. - range (string, required): The A1 notation of the range to update formulas in (e.g. "Sheet1!C1:C2"). - formulas (array of arrays, required): 2D array of formula strings (e.g. [["=A1+B1"], ["=A2+B2"]]).
insert_dimension

Inserts rows or columns in a sheet at a particular index.

Corresponds to an InsertDimensionRequest in the spreadsheets.batchUpdate REST API: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request

Schema: - spreadsheet_id (string, required): The ID of the spreadsheet to update. - sheet_id (integer, required): The ID of the sheet to insert into. - dimension (string, required): "ROWS" or "COLUMNS". - start_index (integer, required): The 0-based start index of the insertion (inclusive). - end_index (integer, required): The 0-based end index of the insertion (exclusive). - inherit_from_before (boolean, optional): Whether dimension properties should be extended from the dimensions before (true) or after (false).

Get MCP tool specifications

To get the MCP tool specifications for all tools in an MCP server, use the tools/list method. The following example demonstrates how to use curl to list all tools and their specifications currently available within the MCP server.

Curl Request 
curl --location 'https://sheetsmcp.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'