mcp-google-sheets Your AI Assistant's Gateway to Google Sheets! ๐ 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. Essentially the serv
Add this skill
npx mdskills install xing5/mcp-google-sheetsComprehensive Google Sheets MCP server with 19+ well-documented tools and flexible authentication options
mcp-google-sheets
Your AI Assistant's Gateway to Google Sheets! ๐
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.
uvx)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 for more information about the IDs used below.
โ๏ธ Prerequisite: Google Cloud Setup
๐ Install uv
uvx is part of uv, a fast Python package installer and resolver. Install it if you haven't already:
# 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.๐ Set Essential Environment Variables (Service Account Recommended)
# 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"
set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json"
set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
$env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json"
$env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
CREDENTIALS_CONFIG).๐ Run the Server!
uvx will automatically download and run the latest version of mcp-google-sheets:
uvx mcp-google-sheets@latest
๐ก Pro Tip: Always use
@latestto ensure you get the newest version with bug fixes and features. Without@latest,uvxmay use a cached older version.
๐ Connect your MCP Client
โก Optional: Enable Tool Filtering (Reduce Context Usage)
You're ready! Start issuing commands via your MCP client.
uvx (zero-install feel) or clone for development using uv.--include-tools or ENABLED_TOOLS environment variable.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.
Solution: Use tool filtering to enable only the tools you actually use.
You can filter tools using either:
Command-line argument --include-tools:
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": [
"mcp-google-sheets@latest",
"--include-tools",
"get_sheet_data,update_cells,list_spreadsheets,list_sheets"
],
"env": {
"SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
}
}
}
}
Environment variable ENABLED_TOOLS:
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": ["mcp-google-sheets@latest"],
"env": {
"SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
"ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
}
}
}
}
When filtering, use these exact tool names (comma-separated, no spaces):
Most Common Tools (recommended subset):
get_sheet_data - Read from spreadsheetsupdate_cells - Write to spreadsheetslist_spreadsheets - Find spreadsheetslist_sheets - Navigate tabsAll Available Tools:
add_columnsadd_rowsbatch_updatebatch_update_cellscopy_sheetcreate_sheetcreate_spreadsheetfind_in_spreadsheetget_multiple_sheet_dataget_multiple_spreadsheet_summaryget_sheet_dataget_sheet_formulaslist_folderslist_sheetslist_spreadsheetsrename_sheetsearch_spreadsheetsshare_spreadsheetupdate_cellsNote: If neither --include-tools nor ENABLED_TOOLS is specified, all tools are enabled (default behavior).
This server exposes the following tools for interacting with Google Sheets:
Refer to the ID Reference Guide for more information about the IDs used below.
(Input parameters are typically strings unless otherwise specified)
list_spreadsheets: Lists spreadsheets in the configured Drive folder (Service Account) or accessible by the user (OAuth).
folder_id (optional string): Google Drive folder ID to search in. Get from its URL. If omitted, uses the configured default folder or searches 'My Drive'.[{id: string, title: string}]create_spreadsheet: Creates a new spreadsheet.
title (string): The desired title for the spreadsheet. Example: "Quarterly Report Q4".folder_id (optional string): Google Drive folder ID where the spreadsheet should be created. Get from its URL. If omitted, uses configured default or root.spreadsheetId, title, and folder.get_sheet_data: Reads data from a range in a sheet/tab.
spreadsheet_id (string): The spreadsheet ID (from its URL).sheet (string): Name of the sheet/tab (e.g., "Sheet1").range (optional string): A1 notation (e.g., 'A1:C10', 'Sheet1!B2:D'). If omitted, reads the whole sheet/tab specified by sheet.include_grid_data (optional boolean, default False): If True, returns full grid data including formatting and metadata (much larger). If False, returns values only (more efficient).include_grid_data=True, full grid data with metadata (get response). If False, a values result object from the Values API (values.get response).get_sheet_formulas: Reads formulas from a range in a sheet/tab.
spreadsheet_id (string): The spreadsheet ID (from its URL).sheet (string): Name of the sheet/tab (e.g., "Sheet1").range (optional string): A1 notation (e.g., 'A1:C10', 'Sheet1!B2:D'). If omitted, reads all formulas in the sheet/tab specified by sheet.values.get response).update_cells: Writes data to a specific range. Overwrites existing data.
spreadsheet_id (string): The spreadsheet ID (from its URL).sheet (string): Name of the sheet/tab (e.g., "Sheet1").range (string): A1 notation range to write to (e.g., 'A1:C3').data (array of arrays): 2D array of values to write. Example: [[1, 2, 3], ["a", "b", "c"]].values.update response).batch_update_cells: Updates multiple ranges in one API call.
spreadsheet_id (string): The spreadsheet ID (from its URL).sheet (string): Name of the sheet/tab (e.g., "Sheet1").ranges (object): Dictionary mapping range strings (A1 notation) to 2D arrays of values. Example: { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }.values.batchUpdate response).add_rows: Adds (inserts) empty rows to a sheet/tab at a specified index.
spreadsheet_id (string): The spreadsheet ID (from its URL).sheet (string): Name of the sheet/tab (e.g., "Sheet1").count (integer): Number of empty rows to insert.start_row (optional integer, default 0): 0-based row index to start inserting rows. If omitted, defaults to 0 (inserts at the beginning).batchUpdate response).list_sheets: Lists all sheet/tab names within a spreadsheet.
spreadsheet_id (string): The spreadsheet ID (from its URL).["Sheet1", "Sheet2"].create_sheet: Adds a new sheet/tab to a spreadsheet.
spreadsheet_id (string): The spreadsheet ID (from its URL).title (string): Name for the new sheet/tab.get_multiple_sheet_data: Fetches data from multiple ranges across potentially different spreadsheets in one call.
queries (array of objects): Each object needs spreadsheet_id, sheet, and range. Example: [{"spreadsheet_id": "abc", "sheet": "Sheet1", "range": "A1:B2"}, ...].data or an error. Each data is a values.get response.get_multiple_spreadsheet_summary: Gets titles, sheet/tab names, headers, and first few rows for multiple spreadsheets.
spreadsheet_ids (array of strings): IDs of the spreadsheets (from their URLs).rows_to_fetch (optional integer, default 5): How many rows (including header) to preview. Example: 5.share_spreadsheet: Shares a spreadsheet with specified users/emails and roles.
spreadsheet_id (string): The spreadsheet ID (from its URL).recipients (array of objects): [{"email_address": "user@example.com", "role": "writer"}, ...]. Roles: reader, commenter, writer.send_notification (optional boolean, default True): Send email notifications to recipients.successes and failures lists.add_columns: Adds (inserts) empty columns to a sheet/tab at a specified index.
spreadsheet_id (string): The spreadsheet ID (from its URL).sheet (string): Name of the sheet/tab (e.g., "Sheet1").count (integer): Number of empty columns to insert.start_column (optional integer, default 0): 0-based column index to start inserting. If omitted, defaults to 0 (inserts at the beginning).batchUpdate response).copy_sheet: Duplicates a sheet/tab from one spreadsheet to another and optionally renames it.
src_spreadsheet (string): Source spreadsheet ID (from its URL).src_sheet (string): Source sheet/tab name (e.g., "Sheet1").dst_spreadsheet (string): Destination spreadsheet ID (from its URL).dst_sheet (string): Desired sheet/tab name in the destination spreadsheet.rename_sheet: Renames an existing sheet/tab.
spreadsheet (string): The spreadsheet ID (from its URL).sheet (string): Current sheet/tab name (e.g., "Sheet1").new_name (string): New sheet/tab name (e.g., "Transactions").batchUpdate response).MCP Resources:
spreadsheet://{spreadsheet_id}/info: Get basic metadata about a Google Spreadsheet.
This setup is required before running the server.
Google Sheets APIGoogle Drive APIThe server needs credentials to access Google APIs. Choose one method:
Refer to the ID Reference Guide for more information about the IDs used below.
mcp-sheets-service).Editor role for broad access, or more granular roles (like roles/drive.file and specific Sheets roles) for stricter permissions.https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID.client_email).SERVICE_ACCOUNT_PATH: Full path to the downloaded JSON key file.DRIVE_FOLDER_ID: The ID of the shared Google Drive folder.
(See Ultra Quick Start for OS-specific examples).../auth/spreadsheets, .../auth/drive), add test users if needed.CREDENTIALS_PATH: Path to the downloaded OAuth credentials JSON file (default: credentials.json).TOKEN_PATH: Path to store the user's refresh token after first login (default: token.json). Must be writable.your_credentials.json.base64 -w 0 your_credentials.json$filePath = "C:\path\to\your_credentials.json"; # Use actual path
$bytes = [System.IO.File]::ReadAllBytes($filePath);
$base64 = [System.Convert]::ToBase64String($bytes);
$base64 # Copy this output
CREDENTIALS_CONFIG: Set this variable to the full Base64 string you just generated.
# Example (Linux/macOS) - Use the actual string generated
export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."
gcloud auth application-default login. No explicit credential files needed.GOOGLE_APPLICATION_CREDENTIALS environment variable (path to service account key) - Google's standard variablegcloud auth application-default login credentials (local development)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 oncegcloud auth application-default set-quota-project (replace `` with your Google Cloud project ID)GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json (Google's standard)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.
The server checks for credentials in this order:
CREDENTIALS_CONFIG (Base64 content)SERVICE_ACCOUNT_PATH (Path to Service Account JSON)CREDENTIALS_PATH (Path to OAuth JSON) - triggers interactive flow if token is missing/expiredEnvironment Variable Summary:
| Variable | Method(s) | Description | Default |
|---|---|---|---|
SERVICE_ACCOUNT_PATH | Service Account | Path to the Service Account JSON key file (MCP server specific). | - |
GOOGLE_APPLICATION_CREDENTIALS | ADC | Path to service account key (Google's standard variable). | - |
DRIVE_FOLDER_ID | Service Account | ID of the Google Drive folder shared with the Service Account. | - |
CREDENTIALS_PATH | OAuth 2.0 | Path to the OAuth 2.0 Client ID JSON file. | credentials.json |
TOKEN_PATH | OAuth 2.0 | Path to store the generated OAuth token. | token.json |
CREDENTIALS_CONFIG | Service Account / OAuth 2.0 | Base64 encoded JSON string of credentials content. | - |
Refer to the ID Reference Guide for more information about the IDs used below.
uvx (Recommended for Users)As shown in the Ultra Quick Start, this is the easiest way. Set environment variables, then run:
uvx mcp-google-sheets@latest
uvx handles fetching and running the package temporarily.
If you want to modify the code:
git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (Use actual URL)uv: (Uses the local code)
uv run mcp-google-sheets
# Or via the script name if defined in pyproject.toml, e.g.:
# uv run start
Run the server in a container using the included Dockerfile:
# Build the image
docker build -t mcp-google-sheets .
# Run (SSE on port 8000)
# NOTE: Prefer CREDENTIALS_CONFIG (Base64 credentials content) in containers.
docker run --rm -p 8000:8000 ^
-e HOST=0.0.0.0 ^
-e PORT=8000 ^
-e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^
-e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^
mcp-google-sheets
CREDENTIALS_CONFIG instead of SERVICE_ACCOUNT_PATH inside Docker to avoid mounting secrets as files.--transport sse and listens on HOST/PORT. Point your MCP client to http://localhost:8000 using SSE transport.Add the server config to claude_desktop_config.json under mcpServers. Choose the block matching your setup:
Refer to the ID Reference Guide for more information about the IDs used below.
โ ๏ธ Important Notes:
"/Users/yourusername/.local/bin/uvx" instead of just "uvx"๐ต Config: uvx + Service Account (Recommended)
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": ["mcp-google-sheets@latest"],
"env": {
"SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
"DRIVE_FOLDER_ID": "your_shared_folder_id_here"
}
}
}
}
๐ macOS Note: If you get a spawn uvx ENOENT error, use the full path to uvx:
{
"mcpServers": {
"google-sheets": {
"command": "/Users/yourusername/.local/bin/uvx",
"args": ["mcp-google-sheets@latest"],
"env": {
"SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
"DRIVE_FOLDER_ID": "your_shared_folder_id_here"
}
}
}
}
Replace yourusername with your actual username.
๐ต Config: uvx + OAuth 2.0
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": ["mcp-google-sheets@latest"],
"env": {
"CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
"TOKEN_PATH": "/full/path/to/your/token.json"
}
}
}
}
Note: A browser may open for Google login on first use. Ensure TOKEN_PATH is writable.
๐ 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).
๐ต Config: uvx + CREDENTIALS_CONFIG (Service Account Example)
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": ["mcp-google-sheets@latest"],
"env": {
"CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
"DRIVE_FOLDER_ID": "your_shared_folder_id_here"
}
}
}
}
Note: Paste the full Base64 string for CREDENTIALS_CONFIG. DRIVE_FOLDER_ID is still needed for Service Account folder context.
๐ 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).
๐ต Config: uvx + Application Default Credentials (ADC)
Option 1: With GOOGLE_APPLICATION_CREDENTIALS
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": ["mcp-google-sheets@latest"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
}
}
}
}
Option 2: With gcloud auth (no env vars needed)
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": ["mcp-google-sheets@latest"],
"env": {}
}
}
}
Prerequisites:
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.gcloud auth application-default set-quota-project ๐ 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).
๐ก Config: Development (Running from cloned repo)
{
"mcpServers": {
"mcp-google-sheets-local": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/your/mcp-google-sheets",
"mcp-google-sheets"
],
"env": {
"SERVICE_ACCOUNT_PATH": "/path/to/your/mcp-google-sheets/service_account.json",
"DRIVE_FOLDER_ID": "your_drive_folder_id_here"
}
}
}
}
Note: Use --directory flag to specify the project path, and adjust paths to match your actual workspace location.
Once connected, try prompts like:
1aBcDeFgHiJkLmNoPqRsTuVwXyZ."XYZ: [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]"team@example.com as a reader and manager@example.com as a writer. Don't send notifications."Use the following reference guide to find the various IDs referenced throughout the docs:
Google Cloud Project ID:
https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
โโโโโโ Project ID โโโโโโ
Google Drive Folder ID:
https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
โโโโโโโโโโโ Folder ID โโโโโโโโโโโ
Google Sheets Spreadsheet ID:
https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
โโโโโโโโโโโโโโ Spreadsheet ID โโโโโโโโโโโโโโ
Contributions are welcome! Please open an issue to discuss bugs or feature requests. Pull requests are appreciated.
This project is licensed under the MIT License - see the LICENSE file for details.
Install via CLI
npx mdskills install xing5/mcp-google-sheetsBuild the image is a free, open-source AI agent skill. mcp-google-sheets Your AI Assistant's Gateway to Google Sheets! ๐ 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. Essentially the serv
Install Build the image with a single command:
npx mdskills install xing5/mcp-google-sheetsThis downloads the skill files into your project and your AI agent picks them up automatically.
Build the image works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.