Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Instructions

Reads values from a specific range in a Google Sheet.

Args:
    user_google_email (str): The user's Google email address. Required.
    spreadsheet_id (str): The ID of the spreadsheet. Required.
    range_name (str): The range to read (e.g., "Sheet1!A1:D10", "A1:D10"). Defaults to "A1:Z1000".

Returns:
    str: The formatted values from the specified range.

Implementation Reference

• gsheets/sheets_tools.py:123-170 (handler)

  The core handler function for the 'read_sheet_values' tool. It reads values from a specified range in a Google Sheet using the Google Sheets API, formats them into a readable text output, and handles errors via decorators.

  @server.tool()
  @handle_http_errors("read_sheet_values", is_read_only=True, service_type="sheets")
  @require_google_service("sheets", "sheets_read")
  async def read_sheet_values(
      service,
      user_google_email: str,
      spreadsheet_id: str,
      range_name: str = "A1:Z1000",
  ) -> str:
      """
      Reads values from a specific range in a Google Sheet.
  
      Args:
          user_google_email (str): The user's Google email address. Required.
          spreadsheet_id (str): The ID of the spreadsheet. Required.
          range_name (str): The range to read (e.g., "Sheet1!A1:D10", "A1:D10"). Defaults to "A1:Z1000".
  
      Returns:
          str: The formatted values from the specified range.
      """
      logger.info(f"[read_sheet_values] Invoked. Email: '{user_google_email}', Spreadsheet: {spreadsheet_id}, Range: {range_name}")
  
      result = await asyncio.to_thread(
          service.spreadsheets()
          .values()
          .get(spreadsheetId=spreadsheet_id, range=range_name)
          .execute
      )
  
      values = result.get("values", [])
      if not values:
          return f"No data found in range '{range_name}' for {user_google_email}."
  
      # Format the output as a readable table
      formatted_rows = []
      for i, row in enumerate(values, 1):
          # Pad row with empty strings to show structure
          padded_row = row + [""] * max(0, len(values[0]) - len(row)) if values else row
          formatted_rows.append(f"Row {i:2d}: {padded_row}")
  
      text_output = (
          f"Successfully read {len(values)} rows from range '{range_name}' in spreadsheet {spreadsheet_id} for {user_google_email}:\n"
          + "\n".join(formatted_rows[:50])  # Limit to first 50 rows for readability
          + (f"\n... and {len(values) - 50} more rows" if len(values) > 50 else "")
      )
  
      logger.info(f"Successfully read {len(values)} rows for {user_google_email}.")
      return text_output

• gsheets/__init__.py:7-23 (registration)

  Imports the 'read_sheet_values' tool from sheets_tools.py and includes it in __all__, effectively registering or exposing it for use in the MCP server.

  from .sheets_tools import (
      list_spreadsheets,
      get_spreadsheet_info,
      read_sheet_values,
      modify_sheet_values,
      create_spreadsheet,
      create_sheet,
  )
  
  __all__ = [
      "list_spreadsheets",
      "get_spreadsheet_info", 
      "read_sheet_values",
      "modify_sheet_values",
      "create_spreadsheet",
      "create_sheet",
  ]