Labsco
xing5 logo

Google Sheets

★ 933

from xing5

A server that connects to the Google Sheets API, enabling AI-driven spreadsheet automation and data manipulation.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#browser#documents#cloud#devops#git#maps
<div align="center"> <!-- Main Title Link --> <b>mcp-google-sheets</b> <!-- Description Paragraph --> <p align="center"> <i>Your AI Assistant's Gateway to Google Sheets! </i>📊 </p>

PyPI - Version PyPI Downloads GitHub License GitHub Actions Workflow Status

</div>

🤔 What is this?

mcp-google-sheets is a Python-based MCP server that acts as a bridge between any MCP-compatible client (like Claude Desktop) and the Google Sheets API. It allows you to interact with your Google Spreadsheets using a defined set of tools, enabling powerful automation and data manipulation workflows driven by AI.

✨ Key Features

  • Seamless Integration: Connects directly to Google Drive & Google Sheets APIs.
  • Comprehensive Tools: Offers a wide range of operations (CRUD, listing, batching, sharing, formatting, etc.).
  • Flexible Authentication: Supports Service Accounts (recommended), OAuth 2.0, and direct credential injection via environment variables.
  • Easy Deployment: Run instantly with uvx (zero-install feel) or clone for development using uv.
  • AI-Ready: Designed for use with MCP-compatible clients, enabling natural language spreadsheet interaction.
  • Tool Filtering: Reduce context window usage by enabling only the tools you need with --include-tools or ENABLED_TOOLS environment variable.

🛠️ Available Tools & Resources

This server exposes the following tools for interacting with Google Sheets:

Refer to the ID Reference Guide for more information about the IDs used below.

(Input parameters are typically strings unless otherwise specified)

  • list_spreadsheets: Lists spreadsheets in the configured Drive folder (Service Account) or accessible by the user (OAuth).
    • folder_id (optional string): Google Drive folder ID to search in. Get from its URL. If omitted, uses the configured default folder or searches 'My Drive'.
    • Returns: List of objects [{id: string, title: string}]
  • create_spreadsheet: Creates a new spreadsheet.
    • title (string): The desired title for the spreadsheet. Example: "Quarterly Report Q4".
    • folder_id (optional string): Google Drive folder ID where the spreadsheet should be created. Get from its URL. If omitted, uses configured default or root.
    • Returns: Object with spreadsheet info, including spreadsheetId, title, and folder.
  • get_sheet_data: Reads data from a range in a sheet/tab.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • sheet (string): Name of the sheet/tab (e.g., "Sheet1").
    • range (optional string): A1 notation (e.g., 'A1:C10', 'Sheet1!B2:D'). If omitted, reads the whole sheet/tab specified by sheet.
    • include_grid_data (optional boolean, default False): If True, returns full grid data including formatting and metadata (much larger). If False, returns values only (more efficient).
    • Returns: If include_grid_data=True, full grid data with metadata (get response). If False, a values result object from the Values API (values.get response).
  • get_sheet_formulas: Reads formulas from a range in a sheet/tab.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • sheet (string): Name of the sheet/tab (e.g., "Sheet1").
    • range (optional string): A1 notation (e.g., 'A1:C10', 'Sheet1!B2:D'). If omitted, reads all formulas in the sheet/tab specified by sheet.
    • Returns: 2D array of cell formulas (array of arrays) (values.get response).
  • update_cells: Writes data to a specific range. Overwrites existing data.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • sheet (string): Name of the sheet/tab (e.g., "Sheet1").
    • range (string): A1 notation range to write to (e.g., 'A1:C3').
    • data (array of arrays): 2D array of values to write. Example: [[1, 2, 3], ["a", "b", "c"]].
    • Returns: Update result object (values.update response).
  • batch_update_cells: Updates multiple ranges in one API call.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • sheet (string): Name of the sheet/tab (e.g., "Sheet1").
    • ranges (object): Dictionary mapping range strings (A1 notation) to 2D arrays of values. Example: { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }.
    • Returns: Result of the operation (values.batchUpdate response).
  • add_rows: Adds (inserts) empty rows to a sheet/tab at a specified index.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • sheet (string): Name of the sheet/tab (e.g., "Sheet1").
    • count (integer): Number of empty rows to insert.
    • start_row (optional integer, default 0): 0-based row index to start inserting rows. If omitted, defaults to 0 (inserts at the beginning).
    • Returns: Result of the operation (batchUpdate response).
  • list_sheets: Lists all sheet/tab names within a spreadsheet.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • Returns: List of sheet/tab name strings. Example: ["Sheet1", "Sheet2"].
  • create_sheet: Adds a new sheet/tab to a spreadsheet.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • title (string): Name for the new sheet/tab.
    • Returns: New sheet properties object.
  • get_multiple_sheet_data: Fetches data from multiple ranges across potentially different spreadsheets in one call.
    • queries (array of objects): Each object needs spreadsheet_id, sheet, and range. Example: [{"spreadsheet_id": "abc", "sheet": "Sheet1", "range": "A1:B2"}, ...].
    • Returns: List of objects, each containing the query params and fetched data or an error. Each data is a values.get response.
  • get_multiple_spreadsheet_summary: Gets titles, sheet/tab names, headers, and first few rows for multiple spreadsheets.
    • spreadsheet_ids (array of strings): IDs of the spreadsheets (from their URLs).
    • rows_to_fetch (optional integer, default 5): How many rows (including header) to preview. Example: 5.
    • Returns: List of summary objects for each spreadsheet.
  • share_spreadsheet: Shares a spreadsheet with specified users/emails and roles.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • recipients (array of objects): [{"email_address": "user@example.com", "role": "writer"}, ...]. Roles: reader, commenter, writer.
    • send_notification (optional boolean, default True): Send email notifications to recipients.
    • Returns: Dictionary with successes and failures lists.
  • add_columns: Adds (inserts) empty columns to a sheet/tab at a specified index.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • sheet (string): Name of the sheet/tab (e.g., "Sheet1").
    • count (integer): Number of empty columns to insert.
    • start_column (optional integer, default 0): 0-based column index to start inserting. If omitted, defaults to 0 (inserts at the beginning).
    • Returns: Result of the operation (batchUpdate response).
  • copy_sheet: Duplicates a sheet/tab from one spreadsheet to another and optionally renames it.
    • src_spreadsheet (string): Source spreadsheet ID (from its URL).
    • src_sheet (string): Source sheet/tab name (e.g., "Sheet1").
    • dst_spreadsheet (string): Destination spreadsheet ID (from its URL).
    • dst_sheet (string): Desired sheet/tab name in the destination spreadsheet.
    • Returns: Result of the copy and optional rename operations.
  • rename_sheet: Renames an existing sheet/tab.
    • spreadsheet (string): The spreadsheet ID (from its URL).
    • sheet (string): Current sheet/tab name (e.g., "Sheet1").
    • new_name (string): New sheet/tab name (e.g., "Transactions").
    • Returns: Result of the operation (batchUpdate response).
  • add_chart: Creates a chart in a Google Spreadsheet from specified data.
    • spreadsheet_id (string): The spreadsheet ID (from its URL).
    • sheet (string): Name of the sheet/tab containing the data (e.g., "Sheet1").
    • chart_type (string): Type of chart to create. Options: COLUMN (vertical bars), BAR (horizontal bars), LINE, AREA, PIE, SCATTER, COMBO, HISTOGRAM.
    • data_range (string): A1 notation range for the chart data (e.g., "A1:C10"). First row is treated as headers.
    • title (optional string): Chart title.
    • x_axis_label (optional string): Label for the X axis (bottom axis). Not applicable for pie charts.
    • y_axis_label (optional string): Label for the Y axis (left axis). Not applicable for pie charts.
    • position_x (optional integer, default 0): Horizontal position offset in pixels from the top-left corner.
    • position_y (optional integer, default 0): Vertical position offset in pixels from the top-left corner.
    • width (optional integer, default 600): Width of the chart in pixels.
    • height (optional integer, default 400): Height of the chart in pixels.
    • Returns: Result object with success status, chart ID, and operation details.

MCP Resources:

  • spreadsheet://{spreadsheet_id}/info: Get basic metadata about a Google Spreadsheet.
    • Returns: JSON string with spreadsheet information.

🔑 Authentication & Environment Variables (Detailed)

The server needs credentials to access Google APIs. Choose one method:

Refer to the ID Reference Guide for more information about the IDs used below.

Method A: Service Account (Recommended for Servers/Automation) ✅

  • Why? Headless (no browser needed), secure, ideal for server environments. Doesn't expire easily.
  • Steps:
    1. Create Service Account: In GCP Console -> "IAM & Admin" -> "Service Accounts".
      • Click "+ CREATE SERVICE ACCOUNT". Name it (e.g., mcp-sheets-service).
      • Grant Roles: Add Editor role for broad access, or more granular roles (like roles/drive.file and specific Sheets roles) for stricter permissions.
      • Click "Done". Find the account, click Actions (⋮) -> "Manage keys".
      • Click "ADD KEY" -> "Create new key" -> JSON -> "CREATE".
      • Download and securely store the JSON key file.
    2. Create & Share Google Drive Folder:
      • In Google Drive, create a folder (e.g., "AI Managed Sheets").
      • Note the Folder ID from the URL: https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID.
      • Right-click the folder -> "Share" -> "Share".
      • Enter the Service Account's email (from the JSON file client_email).
      • Grant Editor access. Uncheck "Notify people". Click "Share".
    3. Set Environment Variables:
      • SERVICE_ACCOUNT_PATH: Full path to the downloaded JSON key file.
      • DRIVE_FOLDER_ID: The ID of the shared Google Drive folder. (See Ultra Quick Start for OS-specific examples)

Method B: OAuth 2.0 (Interactive / Personal Use) 🧑‍💻

  • Why? For personal use or local development where interactive browser login is okay.
  • Steps:
    1. Configure OAuth Consent Screen: In GCP Console -> "APIs & Services" -> "OAuth consent screen". Select "External", fill required info, add scopes (.../auth/spreadsheets, .../auth/drive), add test users if needed.
    2. Create OAuth Client ID: In GCP Console -> "APIs & Services" -> "Credentials". "+ CREATE CREDENTIALS" -> "OAuth client ID" -> Type: Desktop app. Name it. "CREATE". Download JSON.
    3. Set Environment Variables:
      • CREDENTIALS_PATH: Path to the downloaded OAuth credentials JSON file (default: credentials.json).
      • TOKEN_PATH: Path to store the user's refresh token after first login (default: token.json). Must be writable.

Method C: Direct Credential Injection (Advanced) 🔒

  • Why? Useful in environments like Docker, Kubernetes, or CI/CD where managing files is hard, but environment variables are easy/secure. Avoids file system access.
  • How? Instead of providing a path to the credentials file, you provide the content of the file, encoded in Base64, directly in an environment variable.
  • Steps:
    1. Get your credentials JSON file (either Service Account key or OAuth Client ID file). Let's call it your_credentials.json.
    2. Generate the Base64 string:
      • (Linux/macOS): base64 -w 0 your_credentials.json
      • (Windows PowerShell):
        Copy & paste — that's it
        $filePath = "C:\path\to\your_credentials.json"; # Use actual path
$bytes = [System.IO.File]::ReadAllBytes($filePath);
$base64 = [System.Convert]::ToBase64String($bytes);
$base64 # Copy this output
      • (Caution): Avoid pasting sensitive credentials into untrusted online encoders.
    3. Set the Environment Variable:
      • CREDENTIALS_CONFIG: Set this variable to the full Base64 string you just generated.
        Copy & paste — that's it
        # Example (Linux/macOS) - Use the actual string generated
export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."

Method D: Application Default Credentials (ADC) 🌐

  • Why? Ideal for Google Cloud environments (GKE, Compute Engine, Cloud Run) and local development with gcloud auth application-default login. No explicit credential files needed.
  • How? Uses Google's Application Default Credentials chain to automatically discover credentials from multiple sources.
  • ADC Search Order:
    1. GOOGLE_APPLICATION_CREDENTIALS environment variable (path to service account key) - Google's standard variable
    2. gcloud auth application-default login credentials (local development)
    3. Attached service account from metadata server (GKE, Compute Engine, etc.)
  • Setup:
    • Local Development:
      1. Run gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive once
      2. Set a quota project: gcloud auth application-default set-quota-project <project_id> (replace <project_id> with your Google Cloud project ID)
    • Google Cloud: Attach a service account to your compute resource
    • Environment Variable: Set GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json (Google's standard)
  • No additional environment variables needed - ADC is used automatically as a fallback when other methods fail.

Note: GOOGLE_APPLICATION_CREDENTIALS is Google's official standard environment variable, while SERVICE_ACCOUNT_PATH is specific to this MCP server. If you set GOOGLE_APPLICATION_CREDENTIALS, ADC will find it automatically.

Authentication Priority & Summary

The server checks for credentials in this order:

  1. CREDENTIALS_CONFIG (Base64 content)
  2. SERVICE_ACCOUNT_PATH (Path to Service Account JSON)
  3. CREDENTIALS_PATH (Path to OAuth JSON) - triggers interactive flow if token is missing/expired
  4. Application Default Credentials (ADC) - automatic fallback

Environment Variable Summary:

VariableMethod(s)DescriptionDefault
SERVICE_ACCOUNT_PATHService AccountPath to the Service Account JSON key file (MCP server specific).-
GOOGLE_APPLICATION_CREDENTIALSADCPath to service account key (Google's standard variable).-
DRIVE_FOLDER_IDService AccountID of the Google Drive folder shared with the Service Account.-
CREDENTIALS_PATHOAuth 2.0Path to the OAuth 2.0 Client ID JSON file.credentials.json
TOKEN_PATHOAuth 2.0Path to store the generated OAuth token.token.json
CREDENTIALS_CONFIGService Account / OAuth 2.0Base64 encoded JSON string of credentials content.-

💬 Example Prompts for Claude

Once connected, try prompts like:

  • "List all spreadsheets I have access to." (or "in my AI Managed Sheets folder")
  • "Create a new spreadsheet titled 'Quarterly Sales Report Q3 2024'."
  • "In the 'Quarterly Sales Report' spreadsheet, get the data from Sheet1 range A1 to E10."
  • "Add a new sheet named 'Summary' to the spreadsheet with ID 1aBcDeFgHiJkLmNoPqRsTuVwXyZ."
  • "In my 'Project Tasks' spreadsheet, Sheet 'Tasks', update cell B2 to 'In Progress'."
  • "Append these rows to the 'Log' sheet in spreadsheet XYZ: [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]"
  • "Get a summary of the spreadsheets 'Sales Data' and 'Inventory Count'."
  • "Share the 'Team Vacation Schedule' spreadsheet with team@example.com as a reader and manager@example.com as a writer. Don't send notifications."
  • "Create a column chart in my 'Sales Report' spreadsheet showing monthly revenue from data in range A1:B13."
  • "Add a pie chart to the 'Market Analysis' sheet with data from A1:B5 titled 'Market Share by Product'."
  • "In spreadsheet abc123, create a line chart on Sheet1 from range A1:C10 with title 'Growth Trends' and labels 'Month' and 'Revenue'."

🆔 ID Reference Guide

Use the following reference guide to find the various IDs referenced throughout the docs:

Copy & paste — that's it
Google Cloud Project ID:
  https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
                                                          └───── Project ID ─────┘

Google Drive Folder ID:
  https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
                                             └────────── Folder ID ──────────┘

Google Sheets Spreadsheet ID:
  https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
                                         └───────────── Spreadsheet ID ─────────────┘

🤝 Contributing

Contributions are welcome! Please open an issue to discuss bugs or feature requests. Pull requests are appreciated.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits