Skip to content
Back to search

mcp-google-sheets

This MCP server integrates with your Google Drive and Google Sheets, to enable creating and modifying spreadsheets.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xing5--mcp-google-sheets/badge.svg)](/listings/xing5--mcp-google-sheets)

HTML

<a href="/listings/xing5--mcp-google-sheets"><img src="/api/listings/xing5--mcp-google-sheets/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Essentially the server runs in one line: `uvx mcp-google-sheets@latest`.

This 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.

_Refer to the [ID Reference Guide](#-id-reference-guide) for more information about the IDs used below._

1. **☁️ Prerequisite: Google Cloud Setup** * You **must** configure Google Cloud Platform credentials and enable the necessary APIs first. We strongly recommend using a **Service Account**. * ➡️ Jump to the [**Detailed Google Cloud Platform Setup**](#-google-cloud-platform-setup-detailed) guide below.

2. **🐍 Install `uv`** * `uvx` is part of `uv`, a fast Python package installer and resolver. Install it if you haven't already: ```bash # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Or using pip: # pip install uv ``` *Follow instructions in the installer output to add `uv` to your PATH if needed.*

3. **🔑 Set Essential Environment Variables (Service Account Recommended)** * You need to tell the server how to authenticate. Set these variables in your terminal: * **(Linux/macOS)** ```bash # Replace with YOUR actual path and folder ID from the Google Setup step export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json" export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID" ``` * **(Windows CMD)** ```cmd set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json" set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID" ``` * **(Windows PowerShell)** ```powershell $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json" $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID" ``` * ➡️ See [**Detailed Authentication & Environment Variables**](#-authentication--environment-variables-detailed) for other options (OAuth, `CREDENTIALS_CONFIG`).

4. **🏃 Run the Server!** * `uvx` will automatically download and run the latest version of `mcp-google-sheets`: ```bash uvx mcp-google-sheets@latest ``` * The server will start and print logs indicating it's ready. * * > **💡 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.

5. **🔌 Connect your MCP Client** * Configure your client (e.g., Claude Desktop) to connect to the running server. * 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. * ➡️ See [**Usage with Claude Desktop**](#-usage-with-claude-desktop) for examples.

6. **⚡ Optional: Enable Tool Filtering (Reduce Context Usage)** * By default, all 19 tools are enabled (~13K tokens). To reduce context usage, enable only the tools you need. * ➡️ See [**Tool Filtering**](#-tool-filtering-reduce-context-usage) for details.

You're ready! Start issuing commands via your MCP client.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 649 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.