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