gsheets-mcp 0.1.0__tar.gz

gsheets_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+
+# Auth credentials (never commit)
+drive_credentials.json
+token.pickle

gsheets_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Chien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gsheets_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: gsheets-mcp
+Version: 0.1.0
+Summary: Standalone MCP server for Google Sheets operations
+Author: Henry Chien
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.10
+Requires-Dist: google-api-python-client>=2.0.0
+Requires-Dist: google-auth-httplib2>=0.1.0
+Requires-Dist: google-auth-oauthlib>=1.0.0
+Requires-Dist: mcp>=1.0.0

gsheets_mcp-0.1.0/README.md

@@ -0,0 +1,67 @@
+# gsheets-mcp
+
+MCP server for Google Sheets operations.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `gsheet_list_tabs` | List tabs in a spreadsheet by name or ID |
+| `gsheet_read_range` | Read values from a range |
+| `gsheet_update_range` | Update a range with user-entered values |
+| `gsheet_append_rows` | Append rows to a range |
+| `gsheet_create` | Create a new spreadsheet |
+| `gsheet_search` | Search Drive for spreadsheets by name |
+| `gsheet_clear_range` | Clear all values in a range |
+| `gsheet_touch_range` | Rewrite formulas in a range to trigger recalculation |
+
+## Setup
+
+### Prerequisites
+- Python 3.10+
+- Google account with Sheets and Drive API access
+- OAuth desktop client credentials from Google Cloud Console
+
+### Installation
+```bash
+git clone https://github.com/<your-user>/gsheets-mcp.git
+cd gsheets-mcp
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+### Authentication
+1. Save your OAuth desktop credentials file as `drive_credentials.json` in the repository root.
+2. Run an auth bootstrap once:
+```bash
+source venv/bin/activate
+python -c "from src import sheets_client; sheets_client.authenticate()"
+```
+3. Complete browser consent. A local `token.pickle` cache will be created.
+
+### Claude Code Configuration
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "gsheets-mcp": {
+      "type": "stdio",
+      "command": "/path/to/gsheets-mcp/venv/bin/python",
+      "args": ["/path/to/gsheets-mcp/run_server.py"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+source venv/bin/activate
+pytest
+python run_server.py
+```
+
+## License
+MIT

gsheets_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "gsheets-mcp"
+version = "0.1.0"
+description = "Standalone MCP server for Google Sheets operations"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Henry Chien" },
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "google-api-python-client>=2.0.0",
+    "google-auth-oauthlib>=1.0.0",
+    "google-auth-httplib2>=0.1.0",
+]
+
+[project.scripts]
+gsheets-mcp = "src.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]

gsheets_mcp-0.1.0/run_server.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+"""Entry point to run the gsheets-mcp server."""
+
+import sys
+from pathlib import Path
+
+# Add parent to path so 'src' package is importable
+sys.path.insert(0, str(Path(__file__).parent))
+
+from src.server import mcp
+
+if __name__ == "__main__":
+    mcp.run()

gsheets_mcp-0.1.0/src/__init__.py

@@ -0,0 +1 @@
+"""gsheets-mcp package."""

gsheets_mcp-0.1.0/src/server.py

@@ -0,0 +1,238 @@
+"""Standalone MCP server for Google Sheets operations."""
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+from . import sheets_client
+
+mcp = FastMCP(
+    "gsheets-mcp",
+    instructions=(
+        "Google Sheets tools for tab listing, range reads/writes, search, "
+        "sheet creation, range clearing, and range touch/recalc."
+    ),
+)
+
+
+def _json_error(operation: str, error: Exception) -> str:
+    """Return standardized JSON error payload for Sheets tools."""
+    return json.dumps(
+        {
+            "status": "error",
+            "error": str(error),
+            "operation": operation,
+        }
+    )
+
+
+def _validate_render_options(
+    value_render_option: str,
+    date_time_render_option: str,
+) -> None:
+    if value_render_option not in sheets_client.VALID_VALUE_RENDER_OPTIONS:
+        raise ValueError(
+            f"Invalid value_render_option '{value_render_option}'. "
+            f"Must be one of: {sorted(sheets_client.VALID_VALUE_RENDER_OPTIONS)}"
+        )
+    if date_time_render_option not in sheets_client.VALID_DATETIME_RENDER_OPTIONS:
+        raise ValueError(
+            f"Invalid date_time_render_option '{date_time_render_option}'. "
+            f"Must be one of: {sorted(sheets_client.VALID_DATETIME_RENDER_OPTIONS)}"
+        )
+
+
+@mcp.tool()
+def gsheet_list_tabs(spreadsheet: str) -> str:
+    """List tabs in a Google Sheets spreadsheet by name or spreadsheet ID."""
+    try:
+        spreadsheet_id, title = sheets_client.resolve_spreadsheet_id(spreadsheet)
+        sheets_service = sheets_client.get_sheets_service()
+        tabs = sheets_client.list_sheet_tabs(sheets_service, spreadsheet_id)
+        return json.dumps(
+            {
+                "status": "ok",
+                "spreadsheet_id": spreadsheet_id,
+                "title": title,
+                "tabs": tabs,
+            }
+        )
+    except Exception as exc:
+        return _json_error("gsheet_list_tabs", exc)
+
+
+@mcp.tool()
+def gsheet_read_range(
+    spreadsheet: str,
+    cell_range: str,
+    value_render_option: str = "FORMATTED_VALUE",
+    date_time_render_option: str = "FORMATTED_STRING",
+) -> str:
+    """Read values from a range in a Google Sheets spreadsheet."""
+    try:
+        _validate_render_options(value_render_option, date_time_render_option)
+        spreadsheet_id, _ = sheets_client.resolve_spreadsheet_id(spreadsheet)
+        sheets_service = sheets_client.get_sheets_service()
+        values = sheets_client.read_sheet_range(
+            sheets_service,
+            spreadsheet_id,
+            cell_range,
+            value_render_option=value_render_option,
+            date_time_render_option=date_time_render_option,
+        )
+        return json.dumps(
+            {
+                "status": "ok",
+                "spreadsheet_id": spreadsheet_id,
+                "range": cell_range,
+                "value_render_option": value_render_option,
+                "date_time_render_option": date_time_render_option,
+                "values": values,
+            }
+        )
+    except Exception as exc:
+        return _json_error("gsheet_read_range", exc)
+
+
+@mcp.tool()
+def gsheet_update_range(spreadsheet: str, cell_range: str, values: list[list]) -> str:
+    """Update a range in a Google Sheets spreadsheet using USER_ENTERED values."""
+    try:
+        spreadsheet_id, _ = sheets_client.resolve_spreadsheet_id(spreadsheet)
+        sheets_service = sheets_client.get_sheets_service()
+        update_result = sheets_client.update_sheet_range(
+            sheets_service,
+            spreadsheet_id,
+            cell_range,
+            values,
+            value_input_option="USER_ENTERED",
+        )
+        return json.dumps(
+            {
+                "status": "ok",
+                "updatedRange": update_result.get("updatedRange", ""),
+                "updatedCells": update_result.get("updatedCells", 0),
+            }
+        )
+    except Exception as exc:
+        return _json_error("gsheet_update_range", exc)
+
+
+@mcp.tool()
+def gsheet_append_rows(spreadsheet: str, cell_range: str, values: list[list]) -> str:
+    """Append rows to a range in a Google Sheets spreadsheet."""
+    try:
+        spreadsheet_id, _ = sheets_client.resolve_spreadsheet_id(spreadsheet)
+        sheets_service = sheets_client.get_sheets_service()
+        append_result = sheets_client.append_sheet_rows(
+            sheets_service,
+            spreadsheet_id,
+            cell_range,
+            values,
+            value_input_option="USER_ENTERED",
+            insert_data_option="INSERT_ROWS",
+        )
+        return json.dumps(
+            {
+                "status": "ok",
+                "updatedRange": append_result.get("updatedRange", ""),
+                "updatedCells": append_result.get("updatedCells", 0),
+            }
+        )
+    except Exception as exc:
+        return _json_error("gsheet_append_rows", exc)
+
+
+@mcp.tool()
+def gsheet_create(title: str) -> str:
+    """Create a new Google Sheets spreadsheet."""
+    try:
+        sheets_service = sheets_client.get_sheets_service()
+        spreadsheet_id, url = sheets_client.create_spreadsheet(sheets_service, title)
+        return json.dumps(
+            {
+                "status": "ok",
+                "spreadsheet_id": spreadsheet_id,
+                "url": url,
+            }
+        )
+    except Exception as exc:
+        return _json_error("gsheet_create", exc)
+
+
+@mcp.tool()
+def gsheet_search(query: str, max_results: int = 10) -> str:
+    """Search Google Drive for spreadsheets by name."""
+    try:
+        if max_results <= 0:
+            raise ValueError("max_results must be > 0")
+        drive_service = sheets_client.authenticate()
+        files = sheets_client.search_spreadsheets(
+            drive_service,
+            query=query,
+            max_results=max_results,
+        )
+        return json.dumps(
+            {
+                "status": "ok",
+                "query": query,
+                "results": files,
+                "count": len(files),
+            }
+        )
+    except Exception as exc:
+        return _json_error("gsheet_search", exc)
+
+
+@mcp.tool()
+def gsheet_clear_range(spreadsheet: str, cell_range: str) -> str:
+    """Clear all values in a range without deleting cells."""
+    try:
+        spreadsheet_id, _ = sheets_client.resolve_spreadsheet_id(spreadsheet)
+        sheets_service = sheets_client.get_sheets_service()
+        clear_result = sheets_client.clear_sheet_range(
+            sheets_service,
+            spreadsheet_id,
+            cell_range,
+        )
+        return json.dumps(
+            {
+                "status": "ok",
+                "spreadsheet_id": spreadsheet_id,
+                "clearedRange": clear_result.get("clearedRange", cell_range),
+            }
+        )
+    except Exception as exc:
+        return _json_error("gsheet_clear_range", exc)
+
+
+@mcp.tool()
+def gsheet_touch_range(spreadsheet: str, cell_range: str) -> str:
+    """Touch a range to force recalculation of custom functions. Reads formulas, clears the range, then rewrites them."""
+    try:
+        spreadsheet_id, _ = sheets_client.resolve_spreadsheet_id(spreadsheet)
+        sheets_service = sheets_client.get_sheets_service()
+        touch_result = sheets_client.touch_sheet_range(
+            sheets_service,
+            spreadsheet_id,
+            cell_range,
+        )
+        return json.dumps(
+            {
+                "status": "ok",
+                "spreadsheet_id": spreadsheet_id,
+                "touchedRange": touch_result.get("touchedRange", cell_range),
+                "touchedCells": touch_result.get("touchedCells", 0),
+            }
+        )
+    except Exception as exc:
+        return _json_error("gsheet_touch_range", exc)
+
+
+def main() -> None:
+    """Run the MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

gsheets_mcp-0.1.0/src/sheets_client.py

@@ -0,0 +1,354 @@
+"""Google Sheets and Drive helpers for gsheets-mcp."""
+
+import logging
+import pickle
+import re
+from pathlib import Path
+
+from google.auth.transport.requests import Request
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+
+SCOPES = [
+    "https://www.googleapis.com/auth/drive.readonly",
+    "https://www.googleapis.com/auth/spreadsheets",
+]
+
+GOOGLE_SHEET_MIME = "application/vnd.google-apps.spreadsheet"
+SPREADSHEET_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{20,}$")
+
+VALID_VALUE_RENDER_OPTIONS = {
+    "FORMATTED_VALUE",
+    "UNFORMATTED_VALUE",
+    "FORMULA",
+}
+VALID_DATETIME_RENDER_OPTIONS = {
+    "SERIAL_NUMBER",
+    "FORMATTED_STRING",
+}
+
+BASE_DIR = Path(__file__).parent.parent
+CREDENTIALS_FILE = BASE_DIR / "drive_credentials.json"
+TOKEN_FILE = BASE_DIR / "token.pickle"
+
+_cached_creds = None
+logger = logging.getLogger(__name__)
+
+
+def _get_missing_scopes(creds) -> list[str]:
+    """Return required scopes that are missing from credentials."""
+    granted = set()
+    if getattr(creds, "scopes", None):
+        granted.update(creds.scopes)
+    if getattr(creds, "granted_scopes", None):
+        granted.update(creds.granted_scopes)
+    return [scope for scope in SCOPES if scope not in granted]
+
+
+def _get_credentials():
+    """Load, refresh, or create OAuth credentials with required scopes."""
+    global _cached_creds
+
+    creds = _cached_creds
+    if creds is None and TOKEN_FILE.exists():
+        with open(TOKEN_FILE, "rb") as token_file:
+            creds = pickle.load(token_file)
+
+    missing_scopes = _get_missing_scopes(creds) if creds else []
+    if missing_scopes:
+        creds = None
+        _cached_creds = None
+        if TOKEN_FILE.exists():
+            TOKEN_FILE.unlink()
+
+    should_save_token = False
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+            should_save_token = True
+        else:
+            if not CREDENTIALS_FILE.exists():
+                raise FileNotFoundError(
+                    f"Credentials file not found at {CREDENTIALS_FILE}. "
+                    "Please copy your drive_credentials.json to the gsheets-mcp folder."
+                )
+            flow = InstalledAppFlow.from_client_secrets_file(
+                str(CREDENTIALS_FILE), SCOPES
+            )
+            creds = flow.run_local_server(port=0)
+            should_save_token = True
+
+    if should_save_token:
+        with open(TOKEN_FILE, "wb") as token_file:
+            pickle.dump(creds, token_file)
+
+    _cached_creds = creds
+    return creds
+
+
+def authenticate():
+    """Authenticate with Google Drive API and return a service object."""
+    creds = _get_credentials()
+    return build("drive", "v3", credentials=creds)
+
+
+def get_sheets_service():
+    """Authenticate with Google Sheets API and return a service object."""
+    creds = _get_credentials()
+    return build("sheets", "v4", credentials=creds)
+
+
+def resolve_spreadsheet_id(name_or_id: str) -> tuple[str, str]:
+    """Resolve a spreadsheet by ID or exact name and return (id, title)."""
+    drive_service = authenticate()
+
+    if SPREADSHEET_ID_PATTERN.match(name_or_id):
+        try:
+            file_info = drive_service.files().get(
+                fileId=name_or_id,
+                supportsAllDrives=True,
+                fields="id, name, mimeType",
+            ).execute()
+            if file_info.get("mimeType") == GOOGLE_SHEET_MIME:
+                return file_info["id"], file_info["name"]
+        except HttpError as exc:
+            if getattr(exc, "resp", None) is None or exc.resp.status != 404:
+                raise
+
+    escaped_name = name_or_id.replace("'", "\\'")
+    query = (
+        f"name = '{escaped_name}' and "
+        f"mimeType = '{GOOGLE_SHEET_MIME}' and "
+        "trashed = false"
+    )
+    results = drive_service.files().list(
+        q=query,
+        supportsAllDrives=True,
+        includeItemsFromAllDrives=True,
+        fields="files(id, name, modifiedTime, webViewLink, parents)",
+    ).execute()
+    files = results.get("files", [])
+
+    if not files:
+        raise ValueError(f"Spreadsheet not found: {name_or_id}")
+
+    if len(files) == 1:
+        file_info = files[0]
+        return file_info["id"], file_info["name"]
+
+    parent_ids: set[str] = set()
+    for file_info in files:
+        for parent_id in file_info.get("parents", []):
+            parent_ids.add(parent_id)
+
+    parent_names: dict[str, str] = {}
+    for parent_id in parent_ids:
+        try:
+            parent_info = drive_service.files().get(
+                fileId=parent_id,
+                supportsAllDrives=True,
+                fields="id, name",
+            ).execute()
+            parent_names[parent_id] = parent_info.get("name", "")
+        except HttpError:
+            parent_names[parent_id] = ""
+
+    candidates = [
+        "Multiple spreadsheets found. Use spreadsheet ID instead. Candidates:"
+    ]
+    for file_info in files:
+        parent_name = ""
+        parent_list = file_info.get("parents", [])
+        if parent_list:
+            parent_name = parent_names.get(parent_list[0], "")
+        candidates.append(
+            f"- id: {file_info.get('id', '')}, "
+            f"name: {file_info.get('name', '')}, "
+            f"modifiedTime: {file_info.get('modifiedTime', '')}, "
+            f"webViewLink: {file_info.get('webViewLink', '')}, "
+            f"parent: {parent_name}"
+        )
+
+    raise ValueError("\n".join(candidates))
+
+
+def list_sheet_tabs(sheets_service, spreadsheet_id: str) -> list[dict]:
+    """List tabs in a spreadsheet."""
+    spreadsheet = sheets_service.spreadsheets().get(
+        spreadsheetId=spreadsheet_id,
+        fields="sheets(properties(title,index,gridProperties(rowCount,columnCount)))",
+    ).execute()
+
+    tabs = []
+    for sheet in spreadsheet.get("sheets", []):
+        props = sheet.get("properties", {})
+        grid = props.get("gridProperties", {})
+        tabs.append(
+            {
+                "title": props.get("title", ""),
+                "index": props.get("index", 0),
+                "rowCount": grid.get("rowCount", 0),
+                "columnCount": grid.get("columnCount", 0),
+            }
+        )
+    return tabs
+
+
+def read_sheet_range(
+    sheets_service,
+    spreadsheet_id: str,
+    range_a1: str,
+    value_render_option: str = "FORMATTED_VALUE",
+    date_time_render_option: str = "FORMATTED_STRING",
+) -> list[list]:
+    """Read values from a spreadsheet range with render option controls."""
+    if value_render_option not in VALID_VALUE_RENDER_OPTIONS:
+        raise ValueError(
+            f"Invalid value_render_option '{value_render_option}'. "
+            f"Must be one of: {sorted(VALID_VALUE_RENDER_OPTIONS)}"
+        )
+    if date_time_render_option not in VALID_DATETIME_RENDER_OPTIONS:
+        raise ValueError(
+            f"Invalid date_time_render_option '{date_time_render_option}'. "
+            f"Must be one of: {sorted(VALID_DATETIME_RENDER_OPTIONS)}"
+        )
+
+    result = sheets_service.spreadsheets().values().get(
+        spreadsheetId=spreadsheet_id,
+        range=range_a1,
+        valueRenderOption=value_render_option,
+        dateTimeRenderOption=date_time_render_option,
+    ).execute()
+    return result.get("values", [])
+
+
+def update_sheet_range(
+    sheets_service,
+    spreadsheet_id: str,
+    range_a1: str,
+    values: list[list],
+    value_input_option: str = "USER_ENTERED",
+) -> dict:
+    """Update a spreadsheet range with values."""
+    if not isinstance(values, list) or not values or any(
+        not isinstance(row, list) for row in values
+    ):
+        raise ValueError("values must be a non-empty list of lists")
+
+    result = sheets_service.spreadsheets().values().update(
+        spreadsheetId=spreadsheet_id,
+        range=range_a1,
+        valueInputOption=value_input_option,
+        body={"values": values},
+    ).execute()
+    return {
+        "updatedCells": result.get("updatedCells", 0),
+        "updatedRange": result.get("updatedRange", ""),
+    }
+
+
+def append_sheet_rows(
+    sheets_service,
+    spreadsheet_id: str,
+    range_a1: str,
+    values: list[list],
+    value_input_option: str = "USER_ENTERED",
+    insert_data_option: str = "INSERT_ROWS",
+) -> dict:
+    """Append rows to a spreadsheet range."""
+    if not isinstance(values, list) or not values or any(
+        not isinstance(row, list) for row in values
+    ):
+        raise ValueError("values must be a non-empty list of lists")
+
+    result = sheets_service.spreadsheets().values().append(
+        spreadsheetId=spreadsheet_id,
+        range=range_a1,
+        valueInputOption=value_input_option,
+        insertDataOption=insert_data_option,
+        body={"values": values},
+    ).execute()
+    updates = result.get("updates", {})
+    return {
+        "updatedCells": updates.get("updatedCells", 0),
+        "updatedRange": updates.get("updatedRange", ""),
+    }
+
+
+def create_spreadsheet(sheets_service, title: str) -> tuple[str, str]:
+    """Create a new spreadsheet and return (spreadsheet_id, spreadsheet_url)."""
+    result = sheets_service.spreadsheets().create(
+        body={"properties": {"title": title}},
+        fields="spreadsheetId,spreadsheetUrl",
+    ).execute()
+    return result.get("spreadsheetId", ""), result.get("spreadsheetUrl", "")
+
+
+def search_spreadsheets(
+    drive_service,
+    query: str,
+    max_results: int = 10,
+) -> list[dict]:
+    """Search Google Drive for spreadsheets by name."""
+    escaped_query = query.replace("'", "\\'")
+    search_query = (
+        f"name contains '{escaped_query}' and "
+        f"mimeType = '{GOOGLE_SHEET_MIME}' and "
+        "trashed = false"
+    )
+    results = drive_service.files().list(
+        q=search_query,
+        supportsAllDrives=True,
+        includeItemsFromAllDrives=True,
+        fields="files(id, name, modifiedTime, webViewLink)",
+        pageSize=max_results,
+    ).execute()
+    return results.get("files", [])
+
+
+def clear_sheet_range(sheets_service, spreadsheet_id: str, range_a1: str) -> dict:
+    """Clear all values in a spreadsheet range."""
+    result = sheets_service.spreadsheets().values().clear(
+        spreadsheetId=spreadsheet_id,
+        range=range_a1,
+        body={},
+    ).execute()
+    return {
+        "clearedRange": result.get("clearedRange", range_a1),
+    }
+
+
+def touch_sheet_range(sheets_service, spreadsheet_id: str, range_a1: str) -> dict:
+    """Force custom-function recalculation by clearing and rewriting a range."""
+    original_values = read_sheet_range(
+        sheets_service,
+        spreadsheet_id,
+        range_a1,
+        value_render_option="FORMULA",
+    )
+    if not original_values:
+        return {"touchedRange": range_a1, "touchedCells": 0}
+
+    clear_sheet_range(sheets_service, spreadsheet_id, range_a1)
+    try:
+        updated = update_sheet_range(
+            sheets_service,
+            spreadsheet_id,
+            range_a1,
+            original_values,
+            value_input_option="USER_ENTERED",
+        )
+    except Exception:
+        logger.warning(
+            "touch_sheet_range update failed after clear; spreadsheet_id=%s range=%s original_values=%r",
+            spreadsheet_id,
+            range_a1,
+            original_values,
+        )
+        raise
+
+    return {
+        "touchedRange": updated.get("updatedRange", range_a1),
+        "touchedCells": updated.get("updatedCells", 0),
+    }

gsheets_mcp-0.1.0/tests/test_sheets_client.py

@@ -0,0 +1,267 @@
+"""Unit tests for gsheets-mcp Sheets client helpers."""
+
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src import sheets_client
+
+
+def _http_404_error() -> Exception:
+    return sheets_client.HttpError(
+        SimpleNamespace(status=404, reason="Not Found"),
+        b"Not Found",
+    )
+
+
+def _files_list_call_args(service_mock) -> dict:
+    return service_mock.files.return_value.list.call_args.kwargs
+
+
+def test_value_render_option_validation() -> None:
+    sheets_service = MagicMock()
+
+    with pytest.raises(ValueError) as exc_info:
+        sheets_client.read_sheet_range(
+            sheets_service,
+            spreadsheet_id="sheet-123",
+            range_a1="Sheet1!A1:A2",
+            value_render_option="BAD_VALUE",
+        )
+
+    msg = str(exc_info.value)
+    assert "Invalid value_render_option 'BAD_VALUE'" in msg
+    assert "FORMULA" in msg
+    assert "FORMATTED_VALUE" in msg
+    assert "UNFORMATTED_VALUE" in msg
+
+
+def test_date_time_render_option_validation() -> None:
+    sheets_service = MagicMock()
+
+    with pytest.raises(ValueError) as exc_info:
+        sheets_client.read_sheet_range(
+            sheets_service,
+            spreadsheet_id="sheet-123",
+            range_a1="Sheet1!A1:A2",
+            date_time_render_option="BAD_DATE",
+        )
+
+    msg = str(exc_info.value)
+    assert "Invalid date_time_render_option 'BAD_DATE'" in msg
+    assert "FORMATTED_STRING" in msg
+    assert "SERIAL_NUMBER" in msg
+
+
+def test_resolve_spreadsheet_id_by_pattern(monkeypatch: pytest.MonkeyPatch) -> None:
+    drive_service = MagicMock()
+    drive_service.files.return_value.get.return_value.execute.return_value = {
+        "id": "abc1234567890XYZ___123",
+        "name": "My Sheet",
+        "mimeType": sheets_client.GOOGLE_SHEET_MIME,
+    }
+    monkeypatch.setattr(sheets_client, "authenticate", lambda: drive_service)
+
+    spreadsheet_id, title = sheets_client.resolve_spreadsheet_id(
+        "abc1234567890XYZ___123"
+    )
+
+    assert spreadsheet_id == "abc1234567890XYZ___123"
+    assert title == "My Sheet"
+    drive_service.files.return_value.get.assert_called_once()
+    drive_service.files.return_value.list.assert_not_called()
+
+
+def test_resolve_spreadsheet_id_by_name(monkeypatch: pytest.MonkeyPatch) -> None:
+    drive_service = MagicMock()
+    drive_service.files.return_value.get.return_value.execute.side_effect = _http_404_error()
+    drive_service.files.return_value.list.return_value.execute.return_value = {
+        "files": [{"id": "sheet-1", "name": "Comps"}]
+    }
+    monkeypatch.setattr(sheets_client, "authenticate", lambda: drive_service)
+
+    spreadsheet_id, title = sheets_client.resolve_spreadsheet_id("Comps")
+
+    assert spreadsheet_id == "sheet-1"
+    assert title == "Comps"
+    list_kwargs = _files_list_call_args(drive_service)
+    assert list_kwargs["supportsAllDrives"] is True
+    assert list_kwargs["includeItemsFromAllDrives"] is True
+    assert "name = 'Comps'" in list_kwargs["q"]
+    assert sheets_client.GOOGLE_SHEET_MIME in list_kwargs["q"]
+
+
+def test_resolve_spreadsheet_ambiguous(monkeypatch: pytest.MonkeyPatch) -> None:
+    drive_service = MagicMock()
+
+    def fake_get(*, fileId, **kwargs):
+        req = MagicMock()
+        if fileId in {"parent-1", "parent-2"}:
+            req.execute.return_value = {"id": fileId, "name": f"Folder {fileId[-1]}"}
+        else:
+            req.execute.side_effect = _http_404_error()
+        return req
+
+    drive_service.files.return_value.get.side_effect = fake_get
+    drive_service.files.return_value.list.return_value.execute.return_value = {
+        "files": [
+            {
+                "id": "sheet-a",
+                "name": "Comps",
+                "modifiedTime": "2026-02-21T00:00:00Z",
+                "webViewLink": "https://docs.google.com/spreadsheets/d/sheet-a",
+                "parents": ["parent-1"],
+            },
+            {
+                "id": "sheet-b",
+                "name": "Comps",
+                "modifiedTime": "2026-02-22T00:00:00Z",
+                "webViewLink": "https://docs.google.com/spreadsheets/d/sheet-b",
+                "parents": ["parent-2"],
+            },
+        ]
+    }
+    monkeypatch.setattr(sheets_client, "authenticate", lambda: drive_service)
+
+    with pytest.raises(ValueError) as exc_info:
+        sheets_client.resolve_spreadsheet_id("Comps")
+
+    msg = str(exc_info.value)
+    assert "Multiple spreadsheets found" in msg
+    assert "sheet-a" in msg
+    assert "sheet-b" in msg
+
+
+def test_search_spreadsheets_filters_mime() -> None:
+    drive_service = MagicMock()
+    drive_service.files.return_value.list.return_value.execute.return_value = {
+        "files": []
+    }
+
+    sheets_client.search_spreadsheets(drive_service, query="Comp", max_results=5)
+
+    list_kwargs = _files_list_call_args(drive_service)
+    assert sheets_client.GOOGLE_SHEET_MIME in list_kwargs["q"]
+    assert "trashed = false" in list_kwargs["q"]
+    assert list_kwargs["pageSize"] == 5
+
+
+def test_search_spreadsheets_shared_drives() -> None:
+    drive_service = MagicMock()
+    drive_service.files.return_value.list.return_value.execute.return_value = {
+        "files": []
+    }
+
+    sheets_client.search_spreadsheets(drive_service, query="Comp")
+
+    list_kwargs = _files_list_call_args(drive_service)
+    assert list_kwargs["supportsAllDrives"] is True
+    assert list_kwargs["includeItemsFromAllDrives"] is True
+
+
+def test_search_spreadsheets_escapes_apostrophes() -> None:
+    drive_service = MagicMock()
+    drive_service.files.return_value.list.return_value.execute.return_value = {
+        "files": []
+    }
+
+    sheets_client.search_spreadsheets(drive_service, query="O'Reilly")
+
+    list_kwargs = _files_list_call_args(drive_service)
+    assert "O\\'Reilly" in list_kwargs["q"]
+
+
+def test_clear_range_calls_api() -> None:
+    sheets_service = MagicMock()
+    clear_execute = (
+        sheets_service.spreadsheets.return_value.values.return_value.clear.return_value.execute
+    )
+    clear_execute.return_value = {"clearedRange": "Sheet1!A1:C10"}
+
+    result = sheets_client.clear_sheet_range(
+        sheets_service,
+        spreadsheet_id="sheet-123",
+        range_a1="Sheet1!A1:C10",
+    )
+
+    sheets_service.spreadsheets.return_value.values.return_value.clear.assert_called_once_with(
+        spreadsheetId="sheet-123",
+        range="Sheet1!A1:C10",
+        body={},
+    )
+    assert result["clearedRange"] == "Sheet1!A1:C10"
+
+
+def test_touch_sheet_range_reads_clears_and_rewrites_in_order() -> None:
+    sheets_service = MagicMock()
+    values_api = sheets_service.spreadsheets.return_value.values.return_value
+    call_order: list[str] = []
+
+    def _record_read():
+        call_order.append("read")
+        return {"values": [["=SF(\"AAPL\",\"income\",\"revenue\")", 42], ["foo", "bar"]]}
+
+    def _record_clear():
+        call_order.append("clear")
+        return {"clearedRange": "Sheet1!A1:B2"}
+
+    def _record_update():
+        call_order.append("update")
+        return {"updatedRange": "Sheet1!A1:B2", "updatedCells": 4}
+
+    values_api.get.return_value.execute.side_effect = _record_read
+    values_api.clear.return_value.execute.side_effect = _record_clear
+    values_api.update.return_value.execute.side_effect = _record_update
+
+    result = sheets_client.touch_sheet_range(
+        sheets_service,
+        spreadsheet_id="sheet-123",
+        range_a1="Sheet1!A1:B2",
+    )
+
+    assert call_order == ["read", "clear", "update"]
+    values_api.get.assert_called_once_with(
+        spreadsheetId="sheet-123",
+        range="Sheet1!A1:B2",
+        valueRenderOption="FORMULA",
+        dateTimeRenderOption="FORMATTED_STRING",
+    )
+    values_api.clear.assert_called_once_with(
+        spreadsheetId="sheet-123",
+        range="Sheet1!A1:B2",
+        body={},
+    )
+    values_api.update.assert_called_once_with(
+        spreadsheetId="sheet-123",
+        range="Sheet1!A1:B2",
+        valueInputOption="USER_ENTERED",
+        body={"values": [["=SF(\"AAPL\",\"income\",\"revenue\")", 42], ["foo", "bar"]]},
+    )
+    assert result == {"touchedRange": "Sheet1!A1:B2", "touchedCells": 4}
+
+
+def test_touch_sheet_range_empty_range_returns_without_writes() -> None:
+    sheets_service = MagicMock()
+    values_api = sheets_service.spreadsheets.return_value.values.return_value
+    values_api.get.return_value.execute.return_value = {"values": []}
+
+    result = sheets_client.touch_sheet_range(
+        sheets_service,
+        spreadsheet_id="sheet-123",
+        range_a1="Sheet1!A1:B2",
+    )
+
+    values_api.get.assert_called_once_with(
+        spreadsheetId="sheet-123",
+        range="Sheet1!A1:B2",
+        valueRenderOption="FORMULA",
+        dateTimeRenderOption="FORMATTED_STRING",
+    )
+    values_api.clear.assert_not_called()
+    values_api.update.assert_not_called()
+    assert result == {"touchedRange": "Sheet1!A1:B2", "touchedCells": 0}