🤔 What is this?
mcp-google-sheets is a Python-based MCP server that acts as a bridge between any MCP-compatible client (like Claude Desktop) and the Google Sheets API. It allows you to interact with your Google Spreadsheets using a defined set of tools, enabling powerful automation and data manipulation workflows driven by AI.
🚀 Quick Start (Using 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
- 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 guide below.
-
🐍 Install
uvuvxis part ofuv, a fast Python package installer and resolver. Install it if you haven't already:
Follow instructions in the installer output to add# 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 uvuvto your PATH if needed.
-
🔑 Set Essential Environment Variables (Service Account Recommended)
- You need to tell the server how to authenticate. Set these variables in your terminal:
- (Linux/macOS)
# 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)
set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json" set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID" - (Windows 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 for other options (OAuth,
CREDENTIALS_CONFIG).
-
🏃 Run the Server!
uvxwill automatically download and run the latest version ofmcp-google-sheets:uvx mcp-google-sheets@latest- The server will start and print logs indicating it's ready.
-
💡 Pro Tip: Always use
@latestto ensure you get the newest version with bug fixes and features. Without , may use a cached older version.
You're ready! Start issuing commands via your MCP client.
✨ Key Features
- Seamless Integration: Connects directly to Google Drive & Google Sheets APIs.
- Comprehensive Tools: Offers a wide range of operations (CRUD, listing, batching, sharing, formatting, etc.).
- Flexible Authentication: Supports Service Accounts (recommended), OAuth 2.0, and direct credential injection via environment variables.
- Easy Deployment: Run instantly with
uvx(zero-install feel) or clone for development usinguv. - AI-Ready: Designed for use with MCP-compatible clients, enabling natural language spreadsheet interaction.
- Tool Filtering: Reduce context window usage by enabling only the tools you need with
--include-toolsorENABLED_TOOLSenvironment variable.
🎯 Tool Filtering (Reduce Context Usage)
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.
How to Enable Tool Filtering
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" } } } }
Available Tool Names
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 tabs
All 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_cells
Note: If neither --include-tools nor ENABLED_TOOLS is specified, all tools are enabled (default behavior).
🛠️ Available Tools & Resources
This server exposes the following tools for interacting with Google Sheets:
Refer to the ID Reference Guide for more information about the IDs used below.
(Input parameters are typically strings unless otherwise specified)
list_spreadsheets: Lists spreadsheets in the configured Drive folder (Service Account) or accessible by the user (OAuth).folder_id(optional string): Google Drive folder ID to search in. Get from its URL. If omitted, uses the configured default folder or searches 'My Drive'.- Returns: List of objects
[{id: string, title: string}]
create_spreadsheet: Creates a new spreadsheet.title(string): The desired title for the spreadsheet. Example: "Quarterly Report Q4".folder_id(optional string): Google Drive folder ID where the spreadsheet should be created. Get from its URL. If omitted, uses configured default or root.- Returns: Object with spreadsheet info, including
spreadsheetId,title, andfolder.
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 bysheet.include_grid_data(optional boolean, defaultFalse): IfTrue, returns full grid data including formatting and metadata (much larger). IfFalse, returns values only (more efficient).- Returns: If
include_grid_data=True, full grid data with metadata (getresponse). IfFalse, a values result object from the Values API (values.getresponse).
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 .
MCP Resources:
spreadsheet://{spreadsheet_id}/info: Get basic metadata about a Google Spreadsheet.- Returns: JSON string with spreadsheet information.
☁️ Google Cloud Platform Setup (Detailed)
This setup is required before running the server.
- Create/Select a GCP Project: Go to the Google Cloud Console.
- Enable APIs: Navigate to "APIs & Services" -> "Library". Search for and enable:
Google Sheets APIGoogle Drive API
- Configure Credentials: You need to choose one authentication method below (Service Account is recommended).
🔑 Authentication & Environment Variables (Detailed)
The server needs credentials to access Google APIs. Choose one method:
Refer to the ID Reference Guide for more information about the IDs used below.
Method A: Service Account (Recommended for Servers/Automation) ✅
- Why? Headless (no browser needed), secure, ideal for server environments. Doesn't expire easily.
- Steps:
- Create Service Account: In GCP Console -> "IAM & Admin" -> "Service Accounts".
- Click "+ CREATE SERVICE ACCOUNT". Name it (e.g.,
mcp-sheets-service). - Grant Roles: Add
Editorrole for broad access, or more granular roles (likeroles/drive.fileand specific Sheets roles) for stricter permissions. - Click "Done". Find the account, click Actions (⋮) -> "Manage keys".
- Click "ADD KEY" -> "Create new key" -> JSON -> "CREATE".
- Download and securely store the JSON key file.
- Click "+ CREATE SERVICE ACCOUNT". Name it (e.g.,
- Create & Share Google Drive Folder:
- In Google Drive, create a folder (e.g., "AI Managed Sheets").
- Note the Folder ID from the URL:
https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID. - Right-click the folder -> "Share" -> "Share".
- Enter the Service Account's email (from the JSON file
client_email). - Grant Editor access. Uncheck "Notify people". Click "Share".
- Set Environment Variables:
SERVICE_ACCOUNT_PATH: Full path to the downloaded JSON key file.DRIVE_FOLDER_ID: The ID of the shared Google Drive folder. (See Ultra Quick Start for OS-specific examples)
- Create Service Account: In GCP Console -> "IAM & Admin" -> "Service Accounts".
Method B: OAuth 2.0 (Interactive / Personal Use) 🧑💻
- Why? For personal use or local development where interactive browser login is okay.
- Steps:
- 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. - Create OAuth Client ID: In GCP Console -> "APIs & Services" -> "Credentials". "+ CREATE CREDENTIALS" -> "OAuth client ID" -> Type: Desktop app. Name it. "CREATE". Download JSON.
- Set Environment Variables:
CREDENTIALS_PATH: Path to the downloaded OAuth credentials JSON file (default:credentials.json).TOKEN_PATH: Path to store the user's refresh token after first login (default:token.json). Must be writable.
- Configure OAuth Consent Screen: In GCP Console -> "APIs & Services" -> "OAuth consent screen". Select "External", fill required info, add scopes (
Method C: Direct Credential Injection (Advanced) 🔒
- Why? Useful in environments like Docker, Kubernetes, or CI/CD where managing files is hard, but environment variables are easy/secure. Avoids file system access.
- How? Instead of providing a path to the credentials file, you provide the content of the file, encoded in Base64, directly in an environment variable.
- Steps:
- Get your credentials JSON file (either Service Account key or OAuth Client ID file). Let's call it
your_credentials.json. - Generate the Base64 string:
- (Linux/macOS):
base64 -w 0 your_credentials.json - (Windows PowerShell):
$filePath = "C:\path\to\your_credentials.json"; # Use actual path $bytes = [System.IO.File]::ReadAllBytes($filePath); $base64 = [System.Convert]::ToBase64String($bytes); $base64 # Copy this output - (Caution): Avoid pasting sensitive credentials into untrusted online encoders.
- (Linux/macOS):
- Set the Environment Variable:
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..."
- Get your credentials JSON file (either Service Account key or OAuth Client ID file). Let's call it
Method D: Application Default Credentials (ADC) 🌐
- Why? Ideal for Google Cloud environments (GKE, Compute Engine, Cloud Run) and local development with
gcloud auth application-default login. No explicit credential files needed. - How? Uses Google's Application Default Credentials chain to automatically discover credentials from multiple sources.
- ADC Search Order:
GOOGLE_APPLICATION_CREDENTIALSenvironment variable (path to service account key) - Google's standard variablegcloud auth application-default logincredentials (local development)- Attached service account from metadata server (GKE, Compute Engine, etc.)
- Setup:
- Local Development:
- 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/driveonce - Set a quota project:
gcloud auth application-default set-quota-project <project_id>(replace<project_id>with your Google Cloud project ID)
- Run
- Google Cloud: Attach a service account to your compute resource
- Environment Variable: Set
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json(Google's standard)
- Local Development:
- No additional environment variables needed - ADC is used automatically as a fallback when other methods fail.
Note: GOOGLE_APPLICATION_CREDENTIALS is Google's official standard environment variable, while SERVICE_ACCOUNT_PATH is specific to this MCP server. If you set GOOGLE_APPLICATION_CREDENTIALS, ADC will find it automatically.
Authentication Priority & Summary
The server checks for credentials in this order:
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/expired- Application Default Credentials (ADC) - automatic fallback
Environment Variable Summary:
⚙️ Running the Server (Detailed)
Refer to the ID Reference Guide for more information about the IDs used below.
Method 1: Using 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.
Method 2: For Development (Cloning the Repo)
If you want to modify the code:
- Clone:
git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets(Use actual URL) - Set Environment Variables: As described above.
- Run using
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
Method 3: Docker (SSE transport)
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
- Use
CREDENTIALS_CONFIGinstead ofSERVICE_ACCOUNT_PATHinside Docker to avoid mounting secrets as files. - The container starts with
--transport sseand listens onHOST/PORT. Point your MCP client tohttp://localhost:8000using SSE transport.
🔌 Usage with Claude Desktop
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:
- 🍎 macOS Users: use the full path:
"/Users/yourusername/.local/bin/uvx"instead of just"uvx"
{
"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.
{
"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).
{
"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).
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:
- 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/drivefirst. - Set quota project:
gcloud auth application-default set-quota-project <project_id>
🍎 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).
{
"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.
💬 Example Prompts for Claude
Once connected, try prompts like:
- "List all spreadsheets I have access to." (or "in my AI Managed Sheets folder")
- "Create a new spreadsheet titled 'Quarterly Sales Report Q3 2024'."
- "In the 'Quarterly Sales Report' spreadsheet, get the data from Sheet1 range A1 to E10."
- "Add a new sheet named 'Summary' to the spreadsheet with ID
1aBcDeFgHiJkLmNoPqRsTuVwXyZ." - "In my 'Project Tasks' spreadsheet, Sheet 'Tasks', update cell B2 to 'In Progress'."
- "Append these rows to the 'Log' sheet in spreadsheet
XYZ:[['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]" - "Get a summary of the spreadsheets 'Sales Data' and 'Inventory Count'."
- "Share the 'Team Vacation Schedule' spreadsheet with
[email protected]as a reader and[email protected]as a writer. Don't send notifications." - "Create a column chart in my 'Sales Report' spreadsheet showing monthly revenue from data in range A1:B13."
- "Add a pie chart to the 'Market Analysis' sheet with data from A1:B5 titled 'Market Share by Product'."
- "In spreadsheet
abc123, create a line chart on Sheet1 from range A1:C10 with title 'Growth Trends' and labels 'Month' and 'Revenue'."
🆔 ID Reference Guide
Use the following reference guide to find the various IDs referenced throughout the docs:
Google Cloud Project ID:
https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
└───── Project ID ─────┘
Google Drive Folder ID:
https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
└────────── Folder ID ──────────┘
Google Sheets Spreadsheet ID:
https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
└───────────── Spreadsheet ID ─────────────┘
🤝 Contributing
Contributions are welcome! Please open an issue to discuss bugs or feature requests. Pull requests are appreciated.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Credits
- Built with FastMCP.
- Inspired by kazz187/mcp-google-spreadsheet.
- Uses Google API Python Client libraries.
