read_sheet_values
Extract formatted data from a specific range in a Google Sheet using the user's email, spreadsheet ID, and range name for precise data retrieval.
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.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| range_name | No | A1:Z1000 | |
| service | Yes | ||
| spreadsheet_id | Yes | ||
| user_google_email | Yes |
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", ]