google-sheets-mcp

Instructions

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

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")