Build the image

1<div align="center">
2  <!-- Main Title Link -->
3  <b>mcp-google-sheets</b>
4 
5  <!-- Description Paragraph -->
6  <p align="center">
7    <i>Your AI Assistant's Gateway to Google Sheets! </i>📊
8  </p>
9 
10[![PyPI - Version](https://img.shields.io/pypi/v/mcp-google-sheets)](https://pypi.org/project/mcp-google-sheets/)
11[![PyPI Downloads](https://static.pepy.tech/badge/mcp-google-sheets)](https://pepy.tech/projects/mcp-google-sheets)
12![GitHub License](https://img.shields.io/github/license/xing5/mcp-google-sheets)
13![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/xing5/mcp-google-sheets/release.yml)
14</div>
15 
16---
17 
18## 🤔 What is this?
19 
20`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.
21 
22---
23 
24## 🚀 Quick Start (Using `uvx`)
25 
26Essentially the server runs in one line: `uvx mcp-google-sheets@latest`. 
27 
28This 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.
29 
30_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._
31 
321.  **☁️ Prerequisite: Google Cloud Setup**
33    *   You **must** configure Google Cloud Platform credentials and enable the necessary APIs first. We strongly recommend using a **Service Account**.
34    *   ➡️ Jump to the [**Detailed Google Cloud Platform Setup**](#-google-cloud-platform-setup-detailed) guide below.
35 
362.  **🐍 Install `uv`**
37    *   `uvx` is part of `uv`, a fast Python package installer and resolver. Install it if you haven't already:
38        ```bash
39        # macOS / Linux
40        curl -LsSf https://astral.sh/uv/install.sh | sh
41        # Windows
42        powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
43        # Or using pip:
44        # pip install uv
45        ```
46        *Follow instructions in the installer output to add `uv` to your PATH if needed.*
47 
483.  **🔑 Set Essential Environment Variables (Service Account Recommended)**
49    *   You need to tell the server how to authenticate. Set these variables in your terminal:
50    *   **(Linux/macOS)**
51        ```bash
52        # Replace with YOUR actual path and folder ID from the Google Setup step
53        export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json"
54        export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
55        ```
56    *   **(Windows CMD)**
57        ```cmd
58        set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json"
59        set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
60        ```
61    *   **(Windows PowerShell)**
62        ```powershell
63        $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json"
64        $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
65        ```
66    *   ➡️ See [**Detailed Authentication & Environment Variables**](#-authentication--environment-variables-detailed) for other options (OAuth, `CREDENTIALS_CONFIG`).
67 
684.  **🏃 Run the Server!**
69    *   `uvx` will automatically download and run the latest version of `mcp-google-sheets`:
70        ```bash
71        uvx mcp-google-sheets@latest
72        ```
73    *   The server will start and print logs indicating it's ready.
74    *   
75    *   > **💡 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.
76 
775.  **🔌 Connect your MCP Client**
78    *   Configure your client (e.g., Claude Desktop) to connect to the running server.
79    *   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.
80    *   ➡️ See [**Usage with Claude Desktop**](#-usage-with-claude-desktop) for examples.
81 
826.  **⚡ Optional: Enable Tool Filtering (Reduce Context Usage)**
83    *   By default, all 19 tools are enabled (~13K tokens). To reduce context usage, enable only the tools you need.
84    *   ➡️ See [**Tool Filtering**](#-tool-filtering-reduce-context-usage) for details.
85 
86You're ready! Start issuing commands via your MCP client.
87 
88---
89 
90## ✨ Key Features
91 
92*   **Seamless Integration:** Connects directly to Google Drive & Google Sheets APIs.
93*   **Comprehensive Tools:** Offers a wide range of operations (CRUD, listing, batching, sharing, formatting, etc.).
94*   **Flexible Authentication:** Supports **Service Accounts (recommended)**, OAuth 2.0, and direct credential injection via environment variables.
95*   **Easy Deployment:** Run instantly with `uvx` (zero-install feel) or clone for development using `uv`.
96*   **AI-Ready:** Designed for use with MCP-compatible clients, enabling natural language spreadsheet interaction.
97*   **Tool Filtering:** Reduce context window usage by enabling only the tools you need with `--include-tools` or `ENABLED_TOOLS` environment variable.
98 
99---
100 
101## 🎯 Tool Filtering (Reduce Context Usage)
102 
103**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.
104 
105**Solution:** Use tool filtering to enable only the tools you actually use.
106 
107### How to Enable Tool Filtering
108 
109You can filter tools using either:
110 
1111. **Command-line argument** `--include-tools`:
112   ```json
113   {
114     "mcpServers": {
115       "google-sheets": {
116         "command": "uvx",
117         "args": [
118           "mcp-google-sheets@latest",
119           "--include-tools",
120           "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
121         ],
122         "env": {
123           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
124         }
125       }
126     }
127   }
128   ```
129 
1302. **Environment variable** `ENABLED_TOOLS`:
131   ```json
132   {
133     "mcpServers": {
134       "google-sheets": {
135         "command": "uvx",
136         "args": ["mcp-google-sheets@latest"],
137         "env": {
138           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
139           "ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
140         }
141       }
142     }
143   }
144   ```
145 
146### Available Tool Names
147 
148When filtering, use these exact tool names (comma-separated, no spaces):
149 
150**Most Common Tools (recommended subset):**
151- `get_sheet_data` - Read from spreadsheets
152- `update_cells` - Write to spreadsheets
153- `list_spreadsheets` - Find spreadsheets
154- `list_sheets` - Navigate tabs
155 
156**All Available Tools:**
157- `add_columns`
158- `add_rows`
159- `batch_update`
160- `batch_update_cells`
161- `copy_sheet`
162- `create_sheet`
163- `create_spreadsheet`
164- `find_in_spreadsheet`
165- `get_multiple_sheet_data`
166- `get_multiple_spreadsheet_summary`
167- `get_sheet_data`
168- `get_sheet_formulas`
169- `list_folders`
170- `list_sheets`
171- `list_spreadsheets`
172- `rename_sheet`
173- `search_spreadsheets`
174- `share_spreadsheet`
175- `update_cells`
176 
177**Note:** If neither `--include-tools` nor `ENABLED_TOOLS` is specified, all tools are enabled (default behavior).
178 
179---
180 
181## 🛠️ Available Tools & Resources
182 
183This server exposes the following tools for interacting with Google Sheets:
184 
185_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._
186 
187*(Input parameters are typically strings unless otherwise specified)*
188 
189*   **`list_spreadsheets`**: Lists spreadsheets in the configured Drive folder (Service Account) or accessible by the user (OAuth).
190    *   `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'.
191    *   _Returns:_ List of objects `[{id: string, title: string}]`
192*   **`create_spreadsheet`**: Creates a new spreadsheet.
193    *   `title` (string): The desired title for the spreadsheet. Example: "Quarterly Report Q4".
194    *   `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.
195    *   _Returns:_ Object with spreadsheet info, including `spreadsheetId`, `title`, and `folder`.
196*   **`get_sheet_data`**: Reads data from a range in a sheet/tab.
197    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).
198    *   `sheet` (string): Name of the sheet/tab (e.g., "Sheet1").
199    *   `range` (optional string): A1 notation (e.g., `'A1:C10'`, `'Sheet1!B2:D'`). If omitted, reads the whole sheet/tab specified by `sheet`.
200    *   `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).
201    *   _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)).
202*   **`get_sheet_formulas`**: Reads formulas from a range in a sheet/tab.
203    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).
204    *   `sheet` (string): Name of the sheet/tab (e.g., "Sheet1").
205    *   `range` (optional string): A1 notation (e.g., `'A1:C10'`, `'Sheet1!B2:D'`). If omitted, reads all formulas in the sheet/tab specified by `sheet`.
206    *   _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)).
207*   **`update_cells`**: Writes data to a specific range. Overwrites existing data.
208    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).
209    *   `sheet` (string): Name of the sheet/tab (e.g., "Sheet1").
210    *   `range` (string): A1 notation range to write to (e.g., 'A1:C3').
211    *   `data` (array of arrays): 2D array of values to write. Example: `[[1, 2, 3], ["a", "b", "c"]]`.
212    *   _Returns:_ Update result object ([`values.update` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/update#response-body)).
213*   **`batch_update_cells`**: Updates multiple ranges in one API call.
214    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).
215    *   `sheet` (string): Name of the sheet/tab (e.g., "Sheet1").
216    *   `ranges` (object): Dictionary mapping range strings (A1 notation) to 2D arrays of values. Example: `{ "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }`.
217    *   _Returns:_ Result of the operation ([`values.batchUpdate` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/batchUpdate#response-body)).
218*   **`add_rows`**: Adds (inserts) empty rows to a sheet/tab at a specified index.
219    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).
220    *   `sheet` (string): Name of the sheet/tab (e.g., "Sheet1").
221    *   `count` (integer): Number of empty rows to insert.
222    *   `start_row` (optional integer, default `0`): 0-based row index to start inserting rows. If omitted, defaults to `0` (inserts at the beginning).
223    *   _Returns:_ Result of the operation ([`batchUpdate` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate#response-body)).
224*   **`list_sheets`**: Lists all sheet/tab names within a spreadsheet.
225    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).
226    *   _Returns:_ List of sheet/tab name strings. Example: `["Sheet1", "Sheet2"]`.
227*   **`create_sheet`**: Adds a new sheet/tab to a spreadsheet.
228    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).
229    *   `title` (string): Name for the new sheet/tab.
230    *   _Returns:_ New sheet properties object.
231*   **`get_multiple_sheet_data`**: Fetches data from multiple ranges across potentially different spreadsheets in one call.
232    *   `queries` (array of objects): Each object needs `spreadsheet_id`, `sheet`, and `range`. Example: `[{"spreadsheet_id": "abc", "sheet": "Sheet1", "range": "A1:B2"}, ...]`.
233    *   _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).
234*   **`get_multiple_spreadsheet_summary`**: Gets titles, sheet/tab names, headers, and first few rows for multiple spreadsheets.
235    *   `spreadsheet_ids` (array of strings): IDs of the spreadsheets (from their URLs).
236    *   `rows_to_fetch` (optional integer, default `5`): How many rows (including header) to preview. Example: `5`.
237    *   _Returns:_ List of summary objects for each spreadsheet.
238*   **`share_spreadsheet`**: Shares a spreadsheet with specified users/emails and roles.
239    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).
240    *   `recipients` (array of objects): `[{"email_address": "user@example.com", "role": "writer"}, ...]`. Roles: `reader`, `commenter`, `writer`.
241    *   `send_notification` (optional boolean, default `True`): Send email notifications to recipients.
242    *   _Returns:_ Dictionary with `successes` and `failures` lists.
243*   **`add_columns`**: Adds (inserts) empty columns to a sheet/tab at a specified index.
244    *   `spreadsheet_id` (string): The spreadsheet ID (from its URL).
245    *   `sheet` (string): Name of the sheet/tab (e.g., "Sheet1").
246    *   `count` (integer): Number of empty columns to insert.
247    *   `start_column` (optional integer, default `0`): 0-based column index to start inserting. If omitted, defaults to `0` (inserts at the beginning).
248    *   _Returns:_ Result of the operation ([`batchUpdate` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate#response-body)).
249*   **`copy_sheet`**: Duplicates a sheet/tab from one spreadsheet to another and optionally renames it.
250    *   `src_spreadsheet` (string): Source spreadsheet ID (from its URL).
251    *   `src_sheet` (string): Source sheet/tab name (e.g., "Sheet1").
252    *   `dst_spreadsheet` (string): Destination spreadsheet ID (from its URL).
253    *   `dst_sheet` (string): Desired sheet/tab name in the destination spreadsheet.
254    *   _Returns:_ Result of the copy and optional rename operations.
255*   **`rename_sheet`**: Renames an existing sheet/tab.
256    *   `spreadsheet` (string): The spreadsheet ID (from its URL).
257    *   `sheet` (string): Current sheet/tab name (e.g., "Sheet1").
258    *   `new_name` (string): New sheet/tab name (e.g., "Transactions").
259    *   _Returns:_ Result of the operation ([`batchUpdate` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate#response-body)).
260 
261**MCP Resources:**
262 
263*   **`spreadsheet://{spreadsheet_id}/info`**: Get basic metadata about a Google Spreadsheet.
264    *   _Returns:_ JSON string with spreadsheet information.
265 
266---
267 
268## ☁️ Google Cloud Platform Setup (Detailed)
269 
270This setup is **required** before running the server.
271 
2721.  **Create/Select a GCP Project:** Go to the [Google Cloud Console](https://console.cloud.google.com/).
2732.  **Enable APIs:** Navigate to "APIs & Services" -> "Library". Search for and enable:
274    *   `Google Sheets API`
275    *   `Google Drive API`
2763.  **Configure Credentials:** You need to choose *one* authentication method below (Service Account is recommended).
277 
278---
279 
280## 🔑 Authentication & Environment Variables (Detailed)
281 
282The server needs credentials to access Google APIs. Choose one method:
283 
284_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._
285 
286### Method A: Service Account (Recommended for Servers/Automation) ✅
287 
288*   **Why?** Headless (no browser needed), secure, ideal for server environments. Doesn't expire easily.
289*   **Steps:**
290    1.  **Create Service Account:** In GCP Console -> "IAM & Admin" -> "Service Accounts".
291        *   Click "+ CREATE SERVICE ACCOUNT". Name it (e.g., `mcp-sheets-service`).
292        *   Grant Roles: Add `Editor` role for broad access, or more granular roles (like `roles/drive.file` and specific Sheets roles) for stricter permissions.
293        *   Click "Done". Find the account, click Actions (⋮) -> "Manage keys".
294        *   Click "ADD KEY" -> "Create new key" -> **JSON** -> "CREATE".
295        *   **Download and securely store** the JSON key file.
296    2.  **Create & Share Google Drive Folder:**
297        *   In [Google Drive](https://drive.google.com/), create a folder (e.g., "AI Managed Sheets").
298        *   Note the **Folder ID** from the URL: `https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID`.
299        *   Right-click the folder -> "Share" -> "Share".
300        *   Enter the Service Account's email (from the JSON file `client_email`).
301        *   Grant **Editor** access. Uncheck "Notify people". Click "Share".
302    3.  **Set Environment Variables:**
303        *   `SERVICE_ACCOUNT_PATH`: Full path to the downloaded JSON key file.
304        *   `DRIVE_FOLDER_ID`: The ID of the shared Google Drive folder.
305        *(See [Ultra Quick Start](#-ultra-quick-start-using-uvx) for OS-specific examples)*
306 
307### Method B: OAuth 2.0 (Interactive / Personal Use) 🧑‍💻
308 
309*   **Why?** For personal use or local development where interactive browser login is okay.
310*   **Steps:**
311    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.
312    2.  **Create OAuth Client ID:** In GCP Console -> "APIs & Services" -> "Credentials". "+ CREATE CREDENTIALS" -> "OAuth client ID" -> Type: **Desktop app**. Name it. "CREATE". **Download JSON**.
313    3.  **Set Environment Variables:**
314        *   `CREDENTIALS_PATH`: Path to the downloaded OAuth credentials JSON file (default: `credentials.json`).
315        *   `TOKEN_PATH`: Path to store the user's refresh token after first login (default: `token.json`). Must be writable.
316 
317### Method C: Direct Credential Injection (Advanced) 🔒
318 
319*   **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.
320*   **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.
321*   **Steps:**
322    1.  **Get your credentials JSON file** (either Service Account key or OAuth Client ID file). Let's call it `your_credentials.json`.
323    2.  **Generate the Base64 string:**
324        *   **(Linux/macOS):** `base64 -w 0 your_credentials.json`
325        *   **(Windows PowerShell):**
326            ```powershell
327            $filePath = "C:\path\to\your_credentials.json"; # Use actual path
328            $bytes = [System.IO.File]::ReadAllBytes($filePath);
329            $base64 = [System.Convert]::ToBase64String($bytes);
330            $base64 # Copy this output
331            ```
332        *   **(Caution):** Avoid pasting sensitive credentials into untrusted online encoders.
333    3.  **Set the Environment Variable:**
334        *   `CREDENTIALS_CONFIG`: Set this variable to the **full Base64 string** you just generated.
335            ```bash
336            # Example (Linux/macOS) - Use the actual string generated
337            export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."
338            ```
339 
340### Method D: Application Default Credentials (ADC) 🌐
341 
342*   **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.
343*   **How?** Uses Google's Application Default Credentials chain to automatically discover credentials from multiple sources.
344*   **ADC Search Order:**
345    1.  `GOOGLE_APPLICATION_CREDENTIALS` environment variable (path to service account key) - **Google's standard variable**
346    2.  `gcloud auth application-default login` credentials (local development)
347    3.  Attached service account from metadata server (GKE, Compute Engine, etc.)
348*   **Setup:**
349    *   **Local Development:** 
350        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
351        2. Set a quota project: `gcloud auth application-default set-quota-project <project_id>` (replace `<project_id>` with your Google Cloud project ID)
352    *   **Google Cloud:** Attach a service account to your compute resource
353    *   **Environment Variable:** Set `GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json` (Google's standard)
354*   **No additional environment variables needed** - ADC is used automatically as a fallback when other methods fail.
355 
356**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.
357 
358### Authentication Priority & Summary
359 
360The server checks for credentials in this order:
361 
3621.  `CREDENTIALS_CONFIG` (Base64 content)
3632.  `SERVICE_ACCOUNT_PATH` (Path to Service Account JSON)
3643.  `CREDENTIALS_PATH` (Path to OAuth JSON) - triggers interactive flow if token is missing/expired
3654.  **Application Default Credentials (ADC)** - automatic fallback
366 
367**Environment Variable Summary:**
368 
369| Variable                         | Method(s)                   | Description                                                      | Default            |
370|:---------------------------------|:----------------------------|:-----------------------------------------------------------------|:-------------------|
371| `SERVICE_ACCOUNT_PATH`           | Service Account             | Path to the Service Account JSON key file (MCP server specific). | -                  |
372| `GOOGLE_APPLICATION_CREDENTIALS` | ADC                         | Path to service account key (Google's standard variable).        | -                  |
373| `DRIVE_FOLDER_ID`                | Service Account             | ID of the Google Drive folder shared with the Service Account.   | -                  |
374| `CREDENTIALS_PATH`               | OAuth 2.0                   | Path to the OAuth 2.0 Client ID JSON file.                       | `credentials.json` |
375| `TOKEN_PATH`                     | OAuth 2.0                   | Path to store the generated OAuth token.                         | `token.json`       |
376| `CREDENTIALS_CONFIG`             | Service Account / OAuth 2.0 | Base64 encoded JSON string of credentials content.               | -                  |
377 
378---
379 
380## ⚙️ Running the Server (Detailed)
381 
382_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._
383 
384### Method 1: Using `uvx` (Recommended for Users)
385 
386As shown in the [Ultra Quick Start](#-ultra-quick-start-using-uvx), this is the easiest way. Set environment variables, then run:
387 
388```bash
389uvx mcp-google-sheets@latest
390```
391`uvx` handles fetching and running the package temporarily.
392 
393### Method 2: For Development (Cloning the Repo)
394 
395If you want to modify the code:
396 
3971.  **Clone:** `git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets` (Use actual URL)
3982.  **Set Environment Variables:** As described above.
3993.  **Run using `uv`:** (Uses the local code)
400    ```bash
401    uv run mcp-google-sheets
402    # Or via the script name if defined in pyproject.toml, e.g.:
403    # uv run start
404    ```
405 
406### Method 3: Docker (SSE transport)
407 
408Run the server in a container using the included `Dockerfile`:
409 
410```bash
411# Build the image
412docker build -t mcp-google-sheets .
413 
414# Run (SSE on port 8000)
415# NOTE: Prefer CREDENTIALS_CONFIG (Base64 credentials content) in containers.
416docker run --rm -p 8000:8000 ^
417  -e HOST=0.0.0.0 ^
418  -e PORT=8000 ^
419  -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^
420  -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^
421  mcp-google-sheets
422```
423 
424- Use `CREDENTIALS_CONFIG` instead of `SERVICE_ACCOUNT_PATH` inside Docker to avoid mounting secrets as files.
425- The container starts with `--transport sse` and listens on `HOST`/`PORT`. Point your MCP client to `http://localhost:8000` using SSE transport.
426 
427---
428 
429## 🔌 Usage with Claude Desktop
430 
431Add the server config to `claude_desktop_config.json` under `mcpServers`. Choose the block matching your setup:
432 
433_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._
434 
435**⚠️ Important Notes:**
436- **🍎 macOS Users:** use the full path: `"/Users/yourusername/.local/bin/uvx"` instead of just `"uvx"`
437 
438<details>
439<summary>🔵 Config: uvx + Service Account (Recommended)</summary>
440 
441```json
442{
443  "mcpServers": {
444    "google-sheets": {
445      "command": "uvx",
446      "args": ["mcp-google-sheets@latest"],
447      "env": {
448        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
449        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
450      }
451    }
452  }
453}
454```
455 
456**🍎 macOS Note:** If you get a `spawn uvx ENOENT` error, use the full path to `uvx`:
457```json
458{
459  "mcpServers": {
460    "google-sheets": {
461      "command": "/Users/yourusername/.local/bin/uvx",
462      "args": ["mcp-google-sheets@latest"],
463      "env": {
464        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
465        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
466      }
467    }
468  }
469}
470```
471*Replace `yourusername` with your actual username.*
472</details>
473 
474<details>
475<summary>🔵 Config: uvx + OAuth 2.0</summary>
476 
477```json
478{
479  "mcpServers": {
480    "google-sheets": {
481      "command": "uvx",
482      "args": ["mcp-google-sheets@latest"],
483      "env": {
484        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
485        "TOKEN_PATH": "/full/path/to/your/token.json"
486      }
487    }
488  }
489}
490```
491*Note: A browser may open for Google login on first use. Ensure TOKEN_PATH is writable.*
492 
493**🍎 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).
494</details>
495 
496<details>
497<summary>🔵 Config: uvx + CREDENTIALS_CONFIG (Service Account Example)</summary>
498 
499```json
500{
501  "mcpServers": {
502    "google-sheets": {
503      "command": "uvx",
504      "args": ["mcp-google-sheets@latest"],
505      "env": {
506        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
507        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
508      }
509    }
510  }
511}
512```
513*Note: Paste the full Base64 string for CREDENTIALS_CONFIG. DRIVE_FOLDER_ID is still needed for Service Account folder context.*
514 
515**🍎 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).
516</details>
517 
518<details>
519<summary>🔵 Config: uvx + Application Default Credentials (ADC)</summary>
520 
521**Option 1: With GOOGLE_APPLICATION_CREDENTIALS**
522```json
523{
524  "mcpServers": {
525    "google-sheets": {
526      "command": "uvx",
527      "args": ["mcp-google-sheets@latest"],
528      "env": {
529        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
530      }
531    }
532  }
533}
534```
535 
536**Option 2: With gcloud auth (no env vars needed)**
537```json
538{
539  "mcpServers": {
540    "google-sheets": {
541      "command": "uvx",
542      "args": ["mcp-google-sheets@latest"],
543      "env": {}
544    }
545  }
546}
547```
548*Prerequisites:* 
5491. *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.*
5502. *Set quota project: `gcloud auth application-default set-quota-project <project_id>`*
551 
552**🍎 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).
553</details>
554 
555<details>
556<summary>🟡 Config: Development (Running from cloned repo)</summary>
557 
558```json
559{
560  "mcpServers": {
561    "mcp-google-sheets-local": {
562      "command": "uv",
563      "args": [
564        "run",
565        "--directory",
566        "/path/to/your/mcp-google-sheets",
567        "mcp-google-sheets"
568      ],
569      "env": {
570        "SERVICE_ACCOUNT_PATH": "/path/to/your/mcp-google-sheets/service_account.json",
571        "DRIVE_FOLDER_ID": "your_drive_folder_id_here"
572      }
573    }
574  }
575}
576```
577*Note: Use `--directory` flag to specify the project path, and adjust paths to match your actual workspace location.*
578</details>
579 
580---
581 
582## 💬 Example Prompts for Claude
583 
584Once connected, try prompts like:
585 
586*   "List all spreadsheets I have access to." (or "in my AI Managed Sheets folder")
587*   "Create a new spreadsheet titled 'Quarterly Sales Report Q3 2024'."
588*   "In the 'Quarterly Sales Report' spreadsheet, get the data from Sheet1 range A1 to E10."
589*   "Add a new sheet named 'Summary' to the spreadsheet with ID `1aBcDeFgHiJkLmNoPqRsTuVwXyZ`."
590*   "In my 'Project Tasks' spreadsheet, Sheet 'Tasks', update cell B2 to 'In Progress'."
591*   "Append these rows to the 'Log' sheet in spreadsheet `XYZ`: `[['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]`"
592*   "Get a summary of the spreadsheets 'Sales Data' and 'Inventory Count'."
593*   "Share the 'Team Vacation Schedule' spreadsheet with `team@example.com` as a reader and `manager@example.com` as a writer. Don't send notifications."
594 
595---
596 
597## 🆔 ID Reference Guide
598 
599Use the following reference guide to find the various IDs referenced throughout the docs:
600 
601```
602Google Cloud Project ID:
603  https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
604                                                          └───── Project ID ─────┘
605 
606Google Drive Folder ID:
607  https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
608                                             └────────── Folder ID ──────────┘
609 
610Google Sheets Spreadsheet ID:
611  https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
612                                         └───────────── Spreadsheet ID ─────────────┘
613```
614 
615---
616 
617## 🤝 Contributing
618 
619Contributions are welcome! Please open an issue to discuss bugs or feature requests. Pull requests are appreciated.
620 
621---
622 
623## 📄 License
624 
625This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
626 
627---
628 
629## 🙏 Credits
630 
631*   Built with [FastMCP](https://github.com/cognitiveapis/fastmcp).
632*   Inspired by [kazz187/mcp-google-spreadsheet](https://github.com/kazz187/mcp-google-spreadsheet).
633*   Uses Google API Python Client libraries.
634