mcp-google-sheets

🤔 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._

1. ☁️ Prerequisite: Google Cloud Setup

2. 🐍 Install `uv`

# 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)

# 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"

4. 🏃 Run the Server!

uvx mcp-google-sheets@latest

5. 🔌 Connect your MCP Client

6. ⚡ Optional: Enable Tool Filtering (Reduce Context Usage)

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 using `uv`.
• 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-tools` or `ENABLED_TOOLS` environment 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:

1. 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"
         }
       }
     }
   }

2. 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 spreadsheets
• `update_cells` - Write to spreadsheets
• `list_spreadsheets` - Find spreadsheets
• `list_sheets` - Navigate tabs

All Available Tools:

• `add_columns`
• `add_rows`
• `batch_update`
• `batch_update_cells`
• `copy_sheet`
• `create_sheet`
• `create_spreadsheet`
• `find_in_spreadsheet`
• `get_multiple_sheet_data`
• `get_multiple_spreadsheet_summary`
• `get_sheet_data`
• `get_sheet_formulas`
• `list_folders`
• `list_sheets`
• `list_spreadsheets`
• `rename_sheet`
• `search_spreadsheets`
• `share_spreadsheet`
• `update_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).
• `create_spreadsheet`: Creates a new spreadsheet.
• `get_sheet_data`: Reads data from a range in a sheet/tab.
• `get_sheet_formulas`: Reads formulas from a range in a sheet/tab.
• `update_cells`: Writes data to a specific range. Overwrites existing data.
• `batch_update_cells`: Updates multiple ranges in one API call.
• `add_rows`: Adds (inserts) empty rows to a sheet/tab at a specified index.
• `list_sheets`: Lists all sheet/tab names within a spreadsheet.
• `create_sheet`: Adds a new sheet/tab to a spreadsheet.
• `get_multiple_sheet_data`: Fetches data from multiple ranges across potentially different spreadsheets in one call.
• `get_multiple_spreadsheet_summary`: Gets titles, sheet/tab names, headers, and first few rows for multiple spreadsheets.
• `share_spreadsheet`: Shares a spreadsheet with specified users/emails and roles.
• `add_columns`: Adds (inserts) empty columns to a sheet/tab at a specified index.
• `copy_sheet`: Duplicates a sheet/tab from one spreadsheet to another and optionally renames it.
• `rename_sheet`: Renames an existing sheet/tab.
• `add_chart`: Creates a chart in a Google Spreadsheet from specified data.

MCP Resources:

• `spreadsheet://{spreadsheet_id}/info`: Get basic metadata about a Google Spreadsheet.

☁️ Google Cloud Platform Setup (Detailed)

This setup is required before running the server.

1. Create/Select a GCP Project: Go to the Google Cloud Console.

2. Enable APIs: Navigate to "APIs & Services" -> "Library". Search for and enable:

3. 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:

1. Create Service Account: In GCP Console -> "IAM & Admin" -> "Service Accounts".

2. Create & Share Google Drive Folder:

3. Set Environment Variables:

*(See Ultra Quick Start for OS-specific examples)*

Method B: OAuth 2.0 (Interactive / Personal Use) 🧑‍💻

• Why? For personal use or local development where interactive browser login is okay.
• Steps:

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.

2. Create OAuth Client ID: In GCP Console -> "APIs & Services" -> "Credentials". "+ CREATE CREDENTIALS" -> "OAuth client ID" -> Type: Desktop app. Name it. "CREATE". Download JSON.

3. Set Environment Variables:

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:

1. Get your credentials JSON file (either Service Account key or OAuth Client ID file). Let's call it `your_credentials.json`.

2. Generate the Base64 string:

$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

3. Set the Environment Variable:

# Example (Linux/macOS) - Use the actual string generated
            export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."

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:

1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable (path to service account key) - Google's standard variable

2. `gcloud auth application-default login` credentials (local development)

3. Attached service account from metadata server (GKE, Compute Engine, etc.)

• Setup:

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

2. Set a quota project: `gcloud auth application-default set-quota-project ` (replace `` with your Google Cloud project ID)

• 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:

1. `CREDENTIALS_CONFIG` (Base64 content)

2. `SERVICE_ACCOUNT_PATH` (Path to Service Account JSON)

3. `CREDENTIALS_PATH` (Path to OAuth JSON) - triggers interactive flow if token is missing/expired

4. 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:

1. Clone: `git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets` (Use actual URL)

2. Set Environment Variables: As described above.

3. 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_CONFIG` instead of `SERVICE_ACCOUNT_PATH` inside Docker to avoid mounting secrets as files.
• The container starts with `--transport sse` and listens on `HOST`/`PORT`. Point your MCP client to `http://localhost:8000` using 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"`

🔵 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:*

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

2. *Set quota project: `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.*

💬 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 `team@example.com` as a reader and `manager@example.com` 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.