google-sheets-mcp

Instructions

Implementation Reference

• gsheet_mcp_server/handler/sheets/analyze_sheet_structure_handler.py:439-477 (handler)

  Core handler function that orchestrates the sheet structure analysis: resolves spreadsheet ID, performs analysis, formats response as JSON.
  def analyze_sheet_structure_handler( drive_service, sheets_service, spreadsheet_name: str, sheet_name: str ) -> str: """ Handler for analyzing sheet structure - simplified overview with separated data detection. """ try: # Get spreadsheet ID spreadsheet_id = get_spreadsheet_id_by_name(drive_service, spreadsheet_name) # Perform simple analysis analysis = analyze_sheet_structure_simple( sheets_service=sheets_service, spreadsheet_id=spreadsheet_id, sheet_name=sheet_name ) result = { "success": True, "spreadsheet_name": spreadsheet_name, "sheet_name": sheet_name, "analysis": analysis, "message": f"Successfully analyzed sheet structure '{sheet_name}' in '{spreadsheet_name}'" } return compact_json_response(result) except Exception as e: error_result = { "success": False, "spreadsheet_name": spreadsheet_name, "sheet_name": sheet_name, "message": f"Error analyzing sheet structure: {str(e)}" } return compact_json_response(error_result)
• gsheet_mcp_server/server.py:218-244 (registration)

  MCP tool registration with @mcp.tool(), input schema via pydantic Field, documentation, and wrapper that initializes services and delegates to core handler.
  @mcp.tool() def analyze_sheet_structure_tool( spreadsheet_name: str = Field(..., description="The name of the Google Spreadsheet"), sheet_name: str = Field(..., description="Name of the specific sheet to analyze") ) -> str: """ Analyze a specific sheet's structure - quick overview. This tool provides a simple overview of what's in the sheet: - Sheet basic info (name, size, hidden status) - Tables (count, names, ranges, sizes) - Charts (count, IDs, positions) - Slicers (count, IDs, positions) - Drawings (count, IDs, positions) - Developer metadata (count, keys, values) - Summary (total elements, sheet type, frozen panes) Args: spreadsheet_name: The name of the Google Spreadsheet sheet_name: Name of the specific sheet to analyze Returns: JSON string with simplified structure overview """ sheets_service, drive_service = _get_google_services() return analyze_sheet_structure_handler(drive_service, sheets_service, spreadsheet_name, sheet_name)
• gsheet_mcp_server/handler/sheets/analyze_sheet_structure_handler.py:7-51 (helper)

  Key helper function that makes the Google Sheets API call to retrieve sheet structure data (properties, tables, charts, etc.) and finds the target sheet.
  def analyze_sheet_structure_simple( sheets_service, spreadsheet_id: str, sheet_name: str ) -> Dict[str, Any]: """ Simple analysis of a sheet structure - quick overview of elements and data. Args: sheets_service: Google Sheets API service spreadsheet_id: ID of the spreadsheet sheet_name: Name of the sheet to analyze Returns: Dictionary with simple sheet structure and data overview """ try: # Get comprehensive spreadsheet data including values result = sheets_service.spreadsheets().get( spreadsheetId=spreadsheet_id, fields="sheets.properties,sheets.charts,sheets.tables,sheets.slicers,sheets.developerMetadata,sheets.drawings,sheets.data" ).execute() sheets = result.get('sheets', []) # Find the specific sheet target_sheet = None for sheet in sheets: props = sheet.get('properties', {}) if props.get('title') == sheet_name: target_sheet = sheet break if not target_sheet: raise RuntimeError(f"Sheet '{sheet_name}' not found in spreadsheet") return process_simple_sheet_analysis(target_sheet, sheets_service, spreadsheet_id, sheet_name) except HttpError as error: error_details = error.error_details[0] if hasattr(error, 'error_details') and error.error_details else {} error_message = error_details.get('message', str(error)) raise RuntimeError(f"Google Sheets API error: {error_message}") except Exception as error: raise RuntimeError(f"Unexpected error analyzing sheet structure: {str(error)}")
• gsheet_mcp_server/server.py:220-221 (schema)

  Pydantic input schema definition for the tool parameters.
  spreadsheet_name: str = Field(..., description="The name of the Google Spreadsheet"), sheet_name: str = Field(..., description="Name of the specific sheet to analyze")