google-sheets-mcp

Instructions

Implementation Reference

• gsheet_mcp_server/handler/sheets/update_sheet_titles_handler.py:147-275 (handler)

  Main handler function that executes the tool logic: validates inputs, retrieves spreadsheet and sheet IDs using helpers, checks for duplicate names, performs batch sheet property updates via Google Sheets API, handles errors, and returns a compact JSON response.

  def update_sheet_titles_handler(
      drive_service,
      sheets_service,
      spreadsheet_name: str,
      sheet_names: List[str],
      new_titles: List[str]
  ) -> str:
      """
      Handler to update sheet titles in a Google Spreadsheet.
      
      Args:
          drive_service: Google Drive service
          sheets_service: Google Sheets service
          spreadsheet_name: Name of the spreadsheet
          sheet_names: List of sheet names to update
          new_titles: List of new titles for the sheets
      
      Returns:
          JSON string with success status and updated sheets info
      """
      try:
          # Validate inputs
          if not sheet_names or not isinstance(sheet_names, list):
              return compact_json_response({
                  "success": False,
                  "message": "Sheet names are required and must be a list."
              })
          
          if not new_titles or not isinstance(new_titles, list):
              return compact_json_response({
                  "success": False,
                  "message": "New titles are required and must be a list."
              })
          
          if len(sheet_names) != len(new_titles):
              return compact_json_response({
                  "success": False,
                  "message": "Number of sheet names must match number of new titles."
              })
          
          if len(sheet_names) == 0:
              return compact_json_response({
                  "success": False,
                  "message": "At least one sheet name is required."
              })
          
          # Validate each new title
          valid_titles = []
          invalid_titles = []
          
          for title in new_titles:
              validation = validate_sheet_name(title)
              if validation["valid"]:
                  valid_titles.append(validation["cleaned_name"])
              else:
                  invalid_titles.append({"title": title, "error": validation["error"]})
          
          if invalid_titles:
              error_messages = [f"'{item['title']}': {item['error']}" for item in invalid_titles]
              return compact_json_response({
                  "success": False,
                  "message": f"Invalid sheet titles: {'; '.join(error_messages)}",
                  "invalid_titles": invalid_titles
              })
          
          if not valid_titles:
              return compact_json_response({
                  "success": False,
                  "message": "No valid sheet titles provided."
              })
          
          # Get spreadsheet ID
          spreadsheet_id = get_spreadsheet_id_by_name(drive_service, spreadsheet_name)
          if not spreadsheet_id:
              return compact_json_response({
                  "success": False,
                  "message": f"Spreadsheet '{spreadsheet_name}' not found."
              })
          
          # Get sheet IDs
          sheet_ids = get_sheet_ids_by_names(sheets_service, spreadsheet_id, sheet_names)
          missing_sheets = [name for name in sheet_names if name not in sheet_ids]
          
          if missing_sheets:
              return compact_json_response({
                  "success": False,
                  "message": f"Sheets not found: {', '.join(missing_sheets)}"
              })
          
          # Check for duplicate names
          duplicate_check = check_duplicate_sheet_names_for_update(sheets_service, spreadsheet_id, valid_titles, sheet_names)
          if duplicate_check["has_duplicates"]:
              return compact_json_response({
                  "success": False,
                  "message": duplicate_check["error"]
              })
          
          # Update sheet titles
          try:
              sheet_id_list = [sheet_ids[name] for name in sheet_names]
              updated_names = update_sheet_titles(sheets_service, spreadsheet_id, sheet_id_list, valid_titles)
              
              # Prepare response
              renamed_sheets = list(zip(sheet_names, updated_names))
              response_data = {
                  "success": True,
                  "spreadsheet_name": spreadsheet_name,
                  "renamed_sheets": renamed_sheets,
                  "sheets_renamed": len(updated_names),
                  "message": f"Successfully updated {len(updated_names)} sheet title(s) in '{spreadsheet_name}'"
              }
              
              return compact_json_response(response_data)
              
          except HttpError as e:
              error_details = e.error_details if hasattr(e, 'error_details') else str(e)
              return compact_json_response({
                  "success": False,
                  "message": f"Failed to update sheet titles: {error_details}",
                  "error_code": e.resp.status if hasattr(e, 'resp') else None
              })
          
      except Exception as e:
          return compact_json_response({
              "success": False,
              "message": f"Unexpected error: {str(e)}",
              "error_type": type(e).__name__
          })

• gsheet_mcp_server/server.py:205-216 (registration)

  Registers the MCP tool 'update_sheet_titles_tool' with @mcp.tool() decorator, defines input schema using Pydantic Field for spreadsheet_name, sheet_names, and new_titles parameters, initializes Google services, and delegates execution to the handler function.

  @mcp.tool()
  def update_sheet_titles_tool(
      spreadsheet_name: str = Field(..., description="The name of the Google Spreadsheet"),
      sheet_names: List[str] = Field(..., description="List of sheet names to rename (put only the names of the sheets you want to rename)"),
      new_titles: List[str] = Field(..., description="List of new titles for the sheets")
  ) -> str:
      """
      Update sheet titles in a Google Spreadsheet.
      """
      sheets_service, drive_service = _get_google_services()
      return update_sheet_titles_handler(drive_service, sheets_service, spreadsheet_name, sheet_names, new_titles)

• gsheet_mcp_server/server.py:207-210 (schema)

  Input schema definition for the tool using Pydantic BaseModel Field with descriptions and required parameters.

      spreadsheet_name: str = Field(..., description="The name of the Google Spreadsheet"),
      sheet_names: List[str] = Field(..., description="List of sheet names to rename (put only the names of the sheets you want to rename)"),
      new_titles: List[str] = Field(..., description="List of new titles for the sheets")
  ) -> str:

• gsheet_mcp_server/handler/sheets/update_sheet_titles_handler.py:110-146 (helper)

  Core helper function that constructs the batchUpdate requests to rename multiple sheets using Google Sheets API and extracts the updated titles from the response.

  def update_sheet_titles(sheets_service, spreadsheet_id: str, sheet_ids: List[int], new_titles: List[str]) -> List[str]:
      """
      Update sheet titles in a Google Spreadsheet.
      
      Args:
          sheets_service: Google Sheets service
          spreadsheet_id: ID of the spreadsheet
          sheet_ids: List of sheet IDs to update
          new_titles: List of new titles for the sheets
      
      Returns:
          List of updated sheet names
      """
      requests = []
      for sheet_id, new_title in zip(sheet_ids, new_titles):
          requests.append({
              "updateSheetProperties": {
                  "properties": {
                      "sheetId": sheet_id,
                      "title": new_title
                  },
                  "fields": "title"
              }
          })
      
      response = sheets_service.spreadsheets().batchUpdate(
          spreadsheetId=spreadsheet_id,
          body={"requests": requests}
      ).execute()
      
      updated_names = []
      for reply in response.get("replies", []):
          if "updateSheetProperties" in reply:
              updated_names.append(reply["updateSheetProperties"]["properties"]["title"])
      
      return updated_names