{"id":26570849,"url":"https://github.com/xing5/mcp-google-sheets","last_synced_at":"2026-05-14T22:01:36.864Z","repository":{"id":283759902,"uuid":"952831973","full_name":"xing5/mcp-google-sheets","owner":"xing5","description":"This MCP server integrates with your Google Drive and Google Sheets, to enable creating and modifying spreadsheets.","archived":false,"fork":false,"pushed_at":"2026-05-14T21:12:23.000Z","size":106,"stargazers_count":859,"open_issues_count":24,"forks_count":201,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-05-14T21:38:00.949Z","etag":null,"topics":["google","mcp","mcp-server","spreadsheet"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xing5.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-22T01:01:45.000Z","updated_at":"2026-05-14T21:12:27.000Z","dependencies_parsed_at":"2025-03-22T02:23:09.671Z","dependency_job_id":"3b307041-c226-41cd-9824-0084ea7eb315","html_url":"https://github.com/xing5/mcp-google-sheets","commit_stats":null,"previous_names":["xing5/mcp-google-sheets"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/xing5/mcp-google-sheets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xing5%2Fmcp-google-sheets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xing5%2Fmcp-google-sheets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xing5%2Fmcp-google-sheets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xing5%2Fmcp-google-sheets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xing5","download_url":"https://codeload.github.com/xing5/mcp-google-sheets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xing5%2Fmcp-google-sheets/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33045145,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google","mcp","mcp-server","spreadsheet"],"created_at":"2025-03-22T22:19:18.485Z","updated_at":"2026-05-14T22:01:36.856Z","avatar_url":"https://github.com/xing5.png","language":"Python","funding_links":[],"categories":["Databases","Data Access \u0026 Integration MCP Servers","サーバー実装","📚 Projects (1974 total)","Community Servers","MCP 服务器精选列表","Legend","🤖 AI/ML","Uncategorized","Data Platforms","Cloud Services","Table of Contents","MCP Frameworks and libraries","Python"],"sub_categories":["Spreadsheets \u0026 No-Code","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eデータベース","MCP Servers","🗄️ 数据库交互","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eDatabases","Uncategorized","How to Submit","Other Tools and Integrations","Python"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003c!-- Main Title Link --\u003e\n  \u003cb\u003emcp-google-sheets\u003c/b\u003e\n\n  \u003c!-- Description Paragraph --\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ci\u003eYour AI Assistant's Gateway to Google Sheets! \u003c/i\u003e📊\n  \u003c/p\u003e\n\n[![PyPI - Version](https://img.shields.io/pypi/v/mcp-google-sheets)](https://pypi.org/project/mcp-google-sheets/)\n[![PyPI Downloads](https://static.pepy.tech/badge/mcp-google-sheets)](https://pepy.tech/projects/mcp-google-sheets)\n![GitHub License](https://img.shields.io/github/license/xing5/mcp-google-sheets)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/xing5/mcp-google-sheets/release.yml)\n\u003c/div\u003e\n\n---\n\n## 🤔 What is this?\n\n`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.\n\n---\n\n## 🚀 Quick Start (Using `uvx`)\n\nEssentially the server runs in one line: `uvx mcp-google-sheets@latest`. \n\nThis command will automatically download the latest code and run it. **We recommend always using `@latest`** to ensure you have the newest version with the latest features and bug fixes.\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n1.  **☁️ Prerequisite: Google Cloud Setup**\n    *   You **must** configure Google Cloud Platform credentials and enable the necessary APIs first. We strongly recommend using a **Service Account**.\n    *   ➡️ Jump to the [**Detailed Google Cloud Platform Setup**](#-google-cloud-platform-setup-detailed) guide below.\n\n2.  **🐍 Install `uv`**\n    *   `uvx` is part of `uv`, a fast Python package installer and resolver. Install it if you haven't already:\n        ```bash\n        # macOS / Linux\n        curl -LsSf https://astral.sh/uv/install.sh | sh\n        # Windows\n        powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n        # Or using pip:\n        # pip install uv\n        ```\n        *Follow instructions in the installer output to add `uv` to your PATH if needed.*\n\n3.  **🔑 Set Essential Environment Variables (Service Account Recommended)**\n    *   You need to tell the server how to authenticate. Set these variables in your terminal:\n    *   **(Linux/macOS)**\n        ```bash\n        # Replace with YOUR actual path and folder ID from the Google Setup step\n        export SERVICE_ACCOUNT_PATH=\"/path/to/your/service-account-key.json\"\n        export DRIVE_FOLDER_ID=\"YOUR_DRIVE_FOLDER_ID\"\n        ```\n    *   **(Windows CMD)**\n        ```cmd\n        set SERVICE_ACCOUNT_PATH=\"C:\\path\\to\\your\\service-account-key.json\"\n        set DRIVE_FOLDER_ID=\"YOUR_DRIVE_FOLDER_ID\"\n        ```\n    *   **(Windows PowerShell)**\n        ```powershell\n        $env:SERVICE_ACCOUNT_PATH = \"C:\\path\\to\\your\\service-account-key.json\"\n        $env:DRIVE_FOLDER_ID = \"YOUR_DRIVE_FOLDER_ID\"\n        ```\n    *   ➡️ See [**Detailed Authentication \u0026 Environment Variables**](#-authentication--environment-variables-detailed) for other options (OAuth, `CREDENTIALS_CONFIG`).\n\n4.  **🏃 Run the Server!**\n    *   `uvx` will automatically download and run the latest version of `mcp-google-sheets`:\n        ```bash\n        uvx mcp-google-sheets@latest\n        ```\n    *   The server will start and print logs indicating it's ready.\n    *   \n    *   \u003e **💡 Pro Tip:** Always use `@latest` to ensure you get the newest version with bug fixes and features. Without `@latest`, `uvx` may use a cached older version.\n\n5.  **🔌 Connect your MCP Client**\n    *   Configure your client (e.g., Claude Desktop) to connect to the running server.\n    *   Depending on the client you use, you might not need step 4 because the client can launch the server for you. But it's a good practice to test run step 4 anyway to make sure things are set up properly.\n    *   ➡️ See [**Usage with Claude Desktop**](#-usage-with-claude-desktop) for examples.\n\n6.  **⚡ Optional: Enable Tool Filtering (Reduce Context Usage)**\n    *   By default, all 19 tools are enabled (~13K tokens). To reduce context usage, enable only the tools you need.\n    *   ➡️ See [**Tool Filtering**](#-tool-filtering-reduce-context-usage) for details.\n\nYou're ready! Start issuing commands via your MCP client.\n\n---\n\n## ✨ Key Features\n\n*   **Seamless Integration:** Connects directly to Google Drive \u0026 Google Sheets APIs.\n*   **Comprehensive Tools:** Offers a wide range of operations (CRUD, listing, batching, sharing, formatting, etc.).\n*   **Flexible Authentication:** Supports **Service Accounts (recommended)**, OAuth 2.0, and direct credential injection via environment variables.\n*   **Easy Deployment:** Run instantly with `uvx` (zero-install feel) or clone for development using `uv`.\n*   **AI-Ready:** Designed for use with MCP-compatible clients, enabling natural language spreadsheet interaction.\n*   **Tool Filtering:** Reduce context window usage by enabling only the tools you need with `--include-tools` or `ENABLED_TOOLS` environment variable.\n\n---\n\n## 🎯 Tool Filtering (Reduce Context Usage)\n\n**Problem:** By default, this MCP server exposes all 19 tools, consuming ~13,000 tokens before any conversation begins. If you only need a few tools, this wastes valuable context window space.\n\n**Solution:** Use tool filtering to enable only the tools you actually use.\n\n### How to Enable Tool Filtering\n\nYou can filter tools using either:\n\n1. **Command-line argument** `--include-tools`:\n   ```json\n   {\n     \"mcpServers\": {\n       \"google-sheets\": {\n         \"command\": \"uvx\",\n         \"args\": [\n           \"mcp-google-sheets@latest\",\n           \"--include-tools\",\n           \"get_sheet_data,update_cells,list_spreadsheets,list_sheets\"\n         ],\n         \"env\": {\n           \"SERVICE_ACCOUNT_PATH\": \"/path/to/credentials.json\"\n         }\n       }\n     }\n   }\n   ```\n\n2. **Environment variable** `ENABLED_TOOLS`:\n   ```json\n   {\n     \"mcpServers\": {\n       \"google-sheets\": {\n         \"command\": \"uvx\",\n         \"args\": [\"mcp-google-sheets@latest\"],\n         \"env\": {\n           \"SERVICE_ACCOUNT_PATH\": \"/path/to/credentials.json\",\n           \"ENABLED_TOOLS\": \"get_sheet_data,update_cells,list_spreadsheets,list_sheets\"\n         }\n       }\n     }\n   }\n   ```\n\n### Available Tool Names\n\nWhen filtering, use these exact tool names (comma-separated, no spaces):\n\n**Most Common Tools (recommended subset):**\n- `get_sheet_data` - Read from spreadsheets\n- `update_cells` - Write to spreadsheets\n- `list_spreadsheets` - Find spreadsheets\n- `list_sheets` - Navigate tabs\n\n**All Available Tools:**\n- `add_columns`\n- `add_rows`\n- `batch_update`\n- `batch_update_cells`\n- `copy_sheet`\n- `create_sheet`\n- `create_spreadsheet`\n- `find_in_spreadsheet`\n- `get_multiple_sheet_data`\n- `get_multiple_spreadsheet_summary`\n- `get_sheet_data`\n- `get_sheet_formulas`\n- `list_folders`\n- `list_sheets`\n- `list_spreadsheets`\n- `rename_sheet`\n- `search_spreadsheets`\n- `share_spreadsheet`\n- `update_cells`\n\n**Note:** If neither `--include-tools` nor `ENABLED_TOOLS` is specified, all tools are enabled (default behavior).\n\n---\n\n## 🛠️ Available Tools \u0026 Resources\n\nThis server exposes the following tools for interacting with Google Sheets:\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n*(Input parameters are typically strings unless otherwise specified)*\n\n*   **`list_spreadsheets`**: Lists spreadsheets in the configured Drive folder (Service Account) or accessible by the user (OAuth).\n    *   `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'.\n    *   _Returns:_ List of objects `[{id: string, title: string}]`\n*   **`create_spreadsheet`**: Creates a new spreadsheet.\n    *   `title` (string): The desired title for the spreadsheet. Example: \"Quarterly Report Q4\".\n    *   `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.\n    *   _Returns:_ Object with spreadsheet info, including `spreadsheetId`, `title`, and `folder`.\n*   **`get_sheet_data`**: Reads data from a range in a sheet/tab.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   `sheet` (string): Name of the sheet/tab (e.g., \"Sheet1\").\n    *   `range` (optional string): A1 notation (e.g., `'A1:C10'`, `'Sheet1!B2:D'`). If omitted, reads the whole sheet/tab specified by `sheet`.\n    *   `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).\n    *   _Returns:_ If `include_grid_data=True`, full grid data with metadata ([`get` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/get#response-body)). If `False`, a values result object from the Values API ([`values.get` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get#response-body)).\n*   **`get_sheet_formulas`**: Reads formulas from a range in a sheet/tab.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   `sheet` (string): Name of the sheet/tab (e.g., \"Sheet1\").\n    *   `range` (optional string): A1 notation (e.g., `'A1:C10'`, `'Sheet1!B2:D'`). If omitted, reads all formulas in the sheet/tab specified by `sheet`.\n    *   _Returns:_ 2D array of cell formulas (array of arrays) ([`values.get` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get#response-body)).\n*   **`update_cells`**: Writes data to a specific range. Overwrites existing data.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   `sheet` (string): Name of the sheet/tab (e.g., \"Sheet1\").\n    *   `range` (string): A1 notation range to write to (e.g., 'A1:C3').\n    *   `data` (array of arrays): 2D array of values to write. Example: `[[1, 2, 3], [\"a\", \"b\", \"c\"]]`.\n    *   _Returns:_ Update result object ([`values.update` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/update#response-body)).\n*   **`batch_update_cells`**: Updates multiple ranges in one API call.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   `sheet` (string): Name of the sheet/tab (e.g., \"Sheet1\").\n    *   `ranges` (object): Dictionary mapping range strings (A1 notation) to 2D arrays of values. Example: `{ \"A1:B2\": [[1, 2], [3, 4]], \"D5\": [[\"Hello\"]] }`.\n    *   _Returns:_ Result of the operation ([`values.batchUpdate` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/batchUpdate#response-body)).\n*   **`add_rows`**: Adds (inserts) empty rows to a sheet/tab at a specified index.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   `sheet` (string): Name of the sheet/tab (e.g., \"Sheet1\").\n    *   `count` (integer): Number of empty rows to insert.\n    *   `start_row` (optional integer, default `0`): 0-based row index to start inserting rows. If omitted, defaults to `0` (inserts at the beginning).\n    *   _Returns:_ Result of the operation ([`batchUpdate` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate#response-body)).\n*   **`list_sheets`**: Lists all sheet/tab names within a spreadsheet.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   _Returns:_ List of sheet/tab name strings. Example: `[\"Sheet1\", \"Sheet2\"]`.\n*   **`create_sheet`**: Adds a new sheet/tab to a spreadsheet.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   `title` (string): Name for the new sheet/tab.\n    *   _Returns:_ New sheet properties object.\n*   **`get_multiple_sheet_data`**: Fetches data from multiple ranges across potentially different spreadsheets in one call.\n    *   `queries` (array of objects): Each object needs `spreadsheet_id`, `sheet`, and `range`. Example: `[{\"spreadsheet_id\": \"abc\", \"sheet\": \"Sheet1\", \"range\": \"A1:B2\"}, ...]`.\n    *   _Returns:_ List of objects, each containing the query params and fetched `data` or an `error`. Each `data` is a [`values.get` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get#response-body).\n*   **`get_multiple_spreadsheet_summary`**: Gets titles, sheet/tab names, headers, and first few rows for multiple spreadsheets.\n    *   `spreadsheet_ids` (array of strings): IDs of the spreadsheets (from their URLs).\n    *   `rows_to_fetch` (optional integer, default `5`): How many rows (including header) to preview. Example: `5`.\n    *   _Returns:_ List of summary objects for each spreadsheet.\n*   **`share_spreadsheet`**: Shares a spreadsheet with specified users/emails and roles.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   `recipients` (array of objects): `[{\"email_address\": \"user@example.com\", \"role\": \"writer\"}, ...]`. Roles: `reader`, `commenter`, `writer`.\n    *   `send_notification` (optional boolean, default `True`): Send email notifications to recipients.\n    *   _Returns:_ Dictionary with `successes` and `failures` lists.\n*   **`add_columns`**: Adds (inserts) empty columns to a sheet/tab at a specified index.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   `sheet` (string): Name of the sheet/tab (e.g., \"Sheet1\").\n    *   `count` (integer): Number of empty columns to insert.\n    *   `start_column` (optional integer, default `0`): 0-based column index to start inserting. If omitted, defaults to `0` (inserts at the beginning).\n    *   _Returns:_ Result of the operation ([`batchUpdate` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate#response-body)).\n*   **`copy_sheet`**: Duplicates a sheet/tab from one spreadsheet to another and optionally renames it.\n    *   `src_spreadsheet` (string): Source spreadsheet ID (from its URL).\n    *   `src_sheet` (string): Source sheet/tab name (e.g., \"Sheet1\").\n    *   `dst_spreadsheet` (string): Destination spreadsheet ID (from its URL).\n    *   `dst_sheet` (string): Desired sheet/tab name in the destination spreadsheet.\n    *   _Returns:_ Result of the copy and optional rename operations.\n*   **`rename_sheet`**: Renames an existing sheet/tab.\n    *   `spreadsheet` (string): The spreadsheet ID (from its URL).\n    *   `sheet` (string): Current sheet/tab name (e.g., \"Sheet1\").\n    *   `new_name` (string): New sheet/tab name (e.g., \"Transactions\").\n    *   _Returns:_ Result of the operation ([`batchUpdate` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate#response-body)).\n*   **`add_chart`**: Creates a chart in a Google Spreadsheet from specified data.\n    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).\n    *   `sheet` (string): Name of the sheet/tab containing the data (e.g., \"Sheet1\").\n    *   `chart_type` (string): Type of chart to create. Options: `COLUMN` (vertical bars), `BAR` (horizontal bars), `LINE`, `AREA`, `PIE`, `SCATTER`, `COMBO`, `HISTOGRAM`.\n    *   `data_range` (string): A1 notation range for the chart data (e.g., \"A1:C10\"). First row is treated as headers.\n    *   `title` (optional string): Chart title.\n    *   `x_axis_label` (optional string): Label for the X axis (bottom axis). Not applicable for pie charts.\n    *   `y_axis_label` (optional string): Label for the Y axis (left axis). Not applicable for pie charts.\n    *   `position_x` (optional integer, default `0`): Horizontal position offset in pixels from the top-left corner.\n    *   `position_y` (optional integer, default `0`): Vertical position offset in pixels from the top-left corner.\n    *   `width` (optional integer, default `600`): Width of the chart in pixels.\n    *   `height` (optional integer, default `400`): Height of the chart in pixels.\n    *   _Returns:_ Result object with success status, chart ID, and operation details.\n\n**MCP Resources:**\n\n*   **`spreadsheet://{spreadsheet_id}/info`**: Get basic metadata about a Google Spreadsheet.\n    *   _Returns:_ JSON string with spreadsheet information.\n\n---\n\n## ☁️ Google Cloud Platform Setup (Detailed)\n\nThis setup is **required** before running the server.\n\n1.  **Create/Select a GCP Project:** Go to the [Google Cloud Console](https://console.cloud.google.com/).\n2.  **Enable APIs:** Navigate to \"APIs \u0026 Services\" -\u003e \"Library\". Search for and enable:\n    *   `Google Sheets API`\n    *   `Google Drive API`\n3.  **Configure Credentials:** You need to choose *one* authentication method below (Service Account is recommended).\n\n---\n\n## 🔑 Authentication \u0026 Environment Variables (Detailed)\n\nThe server needs credentials to access Google APIs. Choose one method:\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n### Method A: Service Account (Recommended for Servers/Automation) ✅\n\n*   **Why?** Headless (no browser needed), secure, ideal for server environments. Doesn't expire easily.\n*   **Steps:**\n    1.  **Create Service Account:** In GCP Console -\u003e \"IAM \u0026 Admin\" -\u003e \"Service Accounts\".\n        *   Click \"+ CREATE SERVICE ACCOUNT\". Name it (e.g., `mcp-sheets-service`).\n        *   Grant Roles: Add `Editor` role for broad access, or more granular roles (like `roles/drive.file` and specific Sheets roles) for stricter permissions.\n        *   Click \"Done\". Find the account, click Actions (⋮) -\u003e \"Manage keys\".\n        *   Click \"ADD KEY\" -\u003e \"Create new key\" -\u003e **JSON** -\u003e \"CREATE\".\n        *   **Download and securely store** the JSON key file.\n    2.  **Create \u0026 Share Google Drive Folder:**\n        *   In [Google Drive](https://drive.google.com/), create a folder (e.g., \"AI Managed Sheets\").\n        *   Note the **Folder ID** from the URL: `https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID`.\n        *   Right-click the folder -\u003e \"Share\" -\u003e \"Share\".\n        *   Enter the Service Account's email (from the JSON file `client_email`).\n        *   Grant **Editor** access. Uncheck \"Notify people\". Click \"Share\".\n    3.  **Set Environment Variables:**\n        *   `SERVICE_ACCOUNT_PATH`: Full path to the downloaded JSON key file.\n        *   `DRIVE_FOLDER_ID`: The ID of the shared Google Drive folder.\n        *(See [Ultra Quick Start](#-ultra-quick-start-using-uvx) for OS-specific examples)*\n\n### Method B: OAuth 2.0 (Interactive / Personal Use) 🧑‍💻\n\n*   **Why?** For personal use or local development where interactive browser login is okay.\n*   **Steps:**\n    1.  **Configure OAuth Consent Screen:** In GCP Console -\u003e \"APIs \u0026 Services\" -\u003e \"OAuth consent screen\". Select \"External\", fill required info, add scopes (`.../auth/spreadsheets`, `.../auth/drive`), add test users if needed.\n    2.  **Create OAuth Client ID:** In GCP Console -\u003e \"APIs \u0026 Services\" -\u003e \"Credentials\". \"+ CREATE CREDENTIALS\" -\u003e \"OAuth client ID\" -\u003e Type: **Desktop app**. Name it. \"CREATE\". **Download JSON**.\n    3.  **Set Environment Variables:**\n        *   `CREDENTIALS_PATH`: Path to the downloaded OAuth credentials JSON file (default: `credentials.json`).\n        *   `TOKEN_PATH`: Path to store the user's refresh token after first login (default: `token.json`). Must be writable.\n\n### Method C: Direct Credential Injection (Advanced) 🔒\n\n*   **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.\n*   **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.\n*   **Steps:**\n    1.  **Get your credentials JSON file** (either Service Account key or OAuth Client ID file). Let's call it `your_credentials.json`.\n    2.  **Generate the Base64 string:**\n        *   **(Linux/macOS):** `base64 -w 0 your_credentials.json`\n        *   **(Windows PowerShell):**\n            ```powershell\n            $filePath = \"C:\\path\\to\\your_credentials.json\"; # Use actual path\n            $bytes = [System.IO.File]::ReadAllBytes($filePath);\n            $base64 = [System.Convert]::ToBase64String($bytes);\n            $base64 # Copy this output\n            ```\n        *   **(Caution):** Avoid pasting sensitive credentials into untrusted online encoders.\n    3.  **Set the Environment Variable:**\n        *   `CREDENTIALS_CONFIG`: Set this variable to the **full Base64 string** you just generated.\n            ```bash\n            # Example (Linux/macOS) - Use the actual string generated\n            export CREDENTIALS_CONFIG=\"ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb...\"\n            ```\n\n### Method D: Application Default Credentials (ADC) 🌐\n\n*   **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.\n*   **How?** Uses Google's Application Default Credentials chain to automatically discover credentials from multiple sources.\n*   **ADC Search Order:**\n    1.  `GOOGLE_APPLICATION_CREDENTIALS` environment variable (path to service account key) - **Google's standard variable**\n    2.  `gcloud auth application-default login` credentials (local development)\n    3.  Attached service account from metadata server (GKE, Compute Engine, etc.)\n*   **Setup:**\n    *   **Local Development:** \n        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\n        2. Set a quota project: `gcloud auth application-default set-quota-project \u003cproject_id\u003e` (replace `\u003cproject_id\u003e` with your Google Cloud project ID)\n    *   **Google Cloud:** Attach a service account to your compute resource\n    *   **Environment Variable:** Set `GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json` (Google's standard)\n*   **No additional environment variables needed** - ADC is used automatically as a fallback when other methods fail.\n\n**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.\n\n### Authentication Priority \u0026 Summary\n\nThe server checks for credentials in this order:\n\n1.  `CREDENTIALS_CONFIG` (Base64 content)\n2.  `SERVICE_ACCOUNT_PATH` (Path to Service Account JSON)\n3.  `CREDENTIALS_PATH` (Path to OAuth JSON) - triggers interactive flow if token is missing/expired\n4.  **Application Default Credentials (ADC)** - automatic fallback\n\n**Environment Variable Summary:**\n\n| Variable                         | Method(s)                   | Description                                                      | Default            |\n|:---------------------------------|:----------------------------|:-----------------------------------------------------------------|:-------------------|\n| `SERVICE_ACCOUNT_PATH`           | Service Account             | Path to the Service Account JSON key file (MCP server specific). | -                  |\n| `GOOGLE_APPLICATION_CREDENTIALS` | ADC                         | Path to service account key (Google's standard variable).        | -                  |\n| `DRIVE_FOLDER_ID`                | Service Account             | ID of the Google Drive folder shared with the Service Account.   | -                  |\n| `CREDENTIALS_PATH`               | OAuth 2.0                   | Path to the OAuth 2.0 Client ID JSON file.                       | `credentials.json` |\n| `TOKEN_PATH`                     | OAuth 2.0                   | Path to store the generated OAuth token.                         | `token.json`       |\n| `CREDENTIALS_CONFIG`             | Service Account / OAuth 2.0 | Base64 encoded JSON string of credentials content.               | -                  |\n\n---\n\n## ⚙️ Running the Server (Detailed)\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n### Method 1: Using `uvx` (Recommended for Users)\n\nAs shown in the [Ultra Quick Start](#-ultra-quick-start-using-uvx), this is the easiest way. Set environment variables, then run:\n\n```bash\nuvx mcp-google-sheets@latest\n```\n`uvx` handles fetching and running the package temporarily.\n\n### Method 2: For Development (Cloning the Repo)\n\nIf you want to modify the code:\n\n1.  **Clone:** `git clone https://github.com/yourusername/mcp-google-sheets.git \u0026\u0026 cd mcp-google-sheets` (Use actual URL)\n2.  **Set Environment Variables:** As described above.\n3.  **Run using `uv`:** (Uses the local code)\n    ```bash\n    uv run mcp-google-sheets\n    # Or via the script name if defined in pyproject.toml, e.g.:\n    # uv run start\n    ```\n\n### Method 3: Docker (SSE transport)\n\nRun the server in a container using the included `Dockerfile`:\n\n```bash\n# Build the image\ndocker build -t mcp-google-sheets .\n\n# Run (SSE on port 8000)\n# NOTE: Prefer CREDENTIALS_CONFIG (Base64 credentials content) in containers.\ndocker run --rm -p 8000:8000 ^\n  -e HOST=0.0.0.0 ^\n  -e PORT=8000 ^\n  -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^\n  -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^\n  mcp-google-sheets\n```\n\n- Use `CREDENTIALS_CONFIG` instead of `SERVICE_ACCOUNT_PATH` inside Docker to avoid mounting secrets as files.\n- The container starts with `--transport sse` and listens on `HOST`/`PORT`. Point your MCP client to `http://localhost:8000` using SSE transport.\n\n---\n\n## 🔌 Usage with Claude Desktop\n\nAdd the server config to `claude_desktop_config.json` under `mcpServers`. Choose the block matching your setup:\n\n_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._\n\n**⚠️ Important Notes:**\n- **🍎 macOS Users:** use the full path: `\"/Users/yourusername/.local/bin/uvx\"` instead of just `\"uvx\"`\n\n\u003cdetails\u003e\n\u003csummary\u003e🔵 Config: uvx + Service Account (Recommended)\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"google-sheets\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-google-sheets@latest\"],\n      \"env\": {\n        \"SERVICE_ACCOUNT_PATH\": \"/full/path/to/your/service-account-key.json\",\n        \"DRIVE_FOLDER_ID\": \"your_shared_folder_id_here\"\n      }\n    }\n  }\n}\n```\n\n**🍎 macOS Note:** If you get a `spawn uvx ENOENT` error, use the full path to `uvx`:\n```json\n{\n  \"mcpServers\": {\n    \"google-sheets\": {\n      \"command\": \"/Users/yourusername/.local/bin/uvx\",\n      \"args\": [\"mcp-google-sheets@latest\"],\n      \"env\": {\n        \"SERVICE_ACCOUNT_PATH\": \"/full/path/to/your/service-account-key.json\",\n        \"DRIVE_FOLDER_ID\": \"your_shared_folder_id_here\"\n      }\n    }\n  }\n}\n```\n*Replace `yourusername` with your actual username.*\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🔵 Config: uvx + OAuth 2.0\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"google-sheets\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-google-sheets@latest\"],\n      \"env\": {\n        \"CREDENTIALS_PATH\": \"/full/path/to/your/credentials.json\",\n        \"TOKEN_PATH\": \"/full/path/to/your/token.json\"\n      }\n    }\n  }\n}\n```\n*Note: A browser may open for Google login on first use. Ensure TOKEN_PATH is writable.*\n\n**🍎 macOS Note:** If you get a `spawn uvx ENOENT` error, replace `\"command\": \"uvx\"` with `\"command\": \"/Users/yourusername/.local/bin/uvx\"` (replace `yourusername` with your actual username).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🔵 Config: uvx + CREDENTIALS_CONFIG (Service Account Example)\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"google-sheets\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-google-sheets@latest\"],\n      \"env\": {\n        \"CREDENTIALS_CONFIG\": \"ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...\",\n        \"DRIVE_FOLDER_ID\": \"your_shared_folder_id_here\"\n      }\n    }\n  }\n}\n```\n*Note: Paste the full Base64 string for CREDENTIALS_CONFIG. DRIVE_FOLDER_ID is still needed for Service Account folder context.*\n\n**🍎 macOS Note:** If you get a `spawn uvx ENOENT` error, replace `\"command\": \"uvx\"` with `\"command\": \"/Users/yourusername/.local/bin/uvx\"` (replace `yourusername` with your actual username).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🔵 Config: uvx + Application Default Credentials (ADC)\u003c/summary\u003e\n\n**Option 1: With GOOGLE_APPLICATION_CREDENTIALS**\n```json\n{\n  \"mcpServers\": {\n    \"google-sheets\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-google-sheets@latest\"],\n      \"env\": {\n        \"GOOGLE_APPLICATION_CREDENTIALS\": \"/path/to/service-account.json\"\n      }\n    }\n  }\n}\n```\n\n**Option 2: With gcloud auth (no env vars needed)**\n```json\n{\n  \"mcpServers\": {\n    \"google-sheets\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-google-sheets@latest\"],\n      \"env\": {}\n    }\n  }\n}\n```\n*Prerequisites:* \n1. *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` first.*\n2. *Set quota project: `gcloud auth application-default set-quota-project \u003cproject_id\u003e`*\n\n**🍎 macOS Note:** If you get a `spawn uvx ENOENT` error, replace `\"command\": \"uvx\"` with `\"command\": \"/Users/yourusername/.local/bin/uvx\"` (replace `yourusername` with your actual username).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🟡 Config: Development (Running from cloned repo)\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-google-sheets-local\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/path/to/your/mcp-google-sheets\",\n        \"mcp-google-sheets\"\n      ],\n      \"env\": {\n        \"SERVICE_ACCOUNT_PATH\": \"/path/to/your/mcp-google-sheets/service_account.json\",\n        \"DRIVE_FOLDER_ID\": \"your_drive_folder_id_here\"\n      }\n    }\n  }\n}\n```\n*Note: Use `--directory` flag to specify the project path, and adjust paths to match your actual workspace location.*\n\u003c/details\u003e\n\n---\n\n## 💬 Example Prompts for Claude\n\nOnce connected, try prompts like:\n\n*   \"List all spreadsheets I have access to.\" (or \"in my AI Managed Sheets folder\")\n*   \"Create a new spreadsheet titled 'Quarterly Sales Report Q3 2024'.\"\n*   \"In the 'Quarterly Sales Report' spreadsheet, get the data from Sheet1 range A1 to E10.\"\n*   \"Add a new sheet named 'Summary' to the spreadsheet with ID `1aBcDeFgHiJkLmNoPqRsTuVwXyZ`.\"\n*   \"In my 'Project Tasks' spreadsheet, Sheet 'Tasks', update cell B2 to 'In Progress'.\"\n*   \"Append these rows to the 'Log' sheet in spreadsheet `XYZ`: `[['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]`\"\n*   \"Get a summary of the spreadsheets 'Sales Data' and 'Inventory Count'.\"\n*   \"Share the 'Team Vacation Schedule' spreadsheet with `team@example.com` as a reader and `manager@example.com` as a writer. Don't send notifications.\"\n*   \"Create a column chart in my 'Sales Report' spreadsheet showing monthly revenue from data in range A1:B13.\"\n*   \"Add a pie chart to the 'Market Analysis' sheet with data from A1:B5 titled 'Market Share by Product'.\"\n*   \"In spreadsheet `abc123`, create a line chart on Sheet1 from range A1:C10 with title 'Growth Trends' and labels 'Month' and 'Revenue'.\"\n\n---\n\n## 🆔 ID Reference Guide\n\nUse the following reference guide to find the various IDs referenced throughout the docs:\n\n```\nGoogle Cloud Project ID:\n  https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456\n                                                          └───── Project ID ─────┘\n\nGoogle Drive Folder ID:\n  https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa\n                                             └────────── Folder ID ──────────┘\n\nGoogle Sheets Spreadsheet ID:\n  https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit\n                                         └───────────── Spreadsheet ID ─────────────┘\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please open an issue to discuss bugs or feature requests. Pull requests are appreciated.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Credits\n\n*   Built with [FastMCP](https://github.com/cognitiveapis/fastmcp).\n*   Inspired by [kazz187/mcp-google-spreadsheet](https://github.com/kazz187/mcp-google-spreadsheet).\n*   Uses Google API Python Client libraries.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxing5%2Fmcp-google-sheets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxing5%2Fmcp-google-sheets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxing5%2Fmcp-google-sheets/lists"}