mcp-google-sheets

By default, the server exposes 19 tools, consuming approximately 13,000 tokens. To save context window space in your AI conversations, you can enable only the specific tools you need using either a command-line argument or an environment variable.

Method 1: Using --include-tools argument

Add the --include-tools flag followed by a comma-separated list of tool names to the args array in your client configuration.

Method 2: Using ENABLED_TOOLS environment variable

Set the ENABLED_TOOLS environment variable in your client configuration with a comma-separated list of tool names.

Note: Tool names must be exact and contain no spaces.

{
  "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"
      }
    }
  }
}

The fastest way to run the server is using uvx, which automatically downloads and runs the latest version.

Prerequisites

1. Google Cloud Setup: You must configure Google Cloud Platform credentials and enable the necessary APIs. Using a Service Account is strongly recommended.
2. Install uv: uvx is part of the uv package manager.

Installation Steps

1. Install uv

• macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
• Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
• via pip: pip install uv

2. Set Environment Variables (Service Account method) Replace the placeholders with your actual service account JSON path and Google Drive folder ID.

• Linux/macOS:

  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"

3. Run the Server

uvx mcp-google-sheets@latest

4. Connect your MCP Client Configure your client (e.g., Claude Desktop) to launch the server. It is recommended to run the command manually once to verify the setup works.

The server requires Google credentials to access Sheets and Drive. You can choose from four authentication methods depending on your environment. The server checks for credentials in the following priority order:

1. CREDENTIALS_CONFIG (Base64 encoded JSON content)
2. SERVICE_ACCOUNT_PATH (Path to Service Account JSON)
3. CREDENTIALS_PATH (Path to OAuth JSON)
4. Application Default Credentials (ADC) (Automatic fallback)

Method A: Service Account (Recommended for Servers/Automation)

Best for headless environments.

1. Create a Service Account in the GCP Console and download the JSON key.
2. Create a folder in Google Drive and note its Folder ID.
3. Share the folder with the Service Account's client_email and grant Editor access.
4. Set SERVICE_ACCOUNT_PATH (path to JSON) and DRIVE_FOLDER_ID.

Method B: OAuth 2.0 (Interactive / Personal Use)

Best for local development where a browser login is acceptable.

1. Configure an OAuth consent screen in GCP with .../auth/spreadsheets and .../auth/drive scopes.
2. Create an OAuth client ID (Desktop app type) and download the JSON.
3. Set CREDENTIALS_PATH (path to JSON) and TOKEN_PATH (where to save the refresh token).

Method C: Direct Credential Injection (Advanced)

Best for Docker, Kubernetes, or CI/CD to avoid managing secret files.

1. Convert your credentials JSON file to a Base64 string.
2. Set the CREDENTIALS_CONFIG environment variable to that Base64 string.

Method D: Application Default Credentials (ADC)

Best for Google Cloud environments (GKE, Compute Engine, etc.).

1. Use gcloud auth application-default login locally with required scopes.
2. Or, set the standard GOOGLE_APPLICATION_CREDENTIALS environment variable.
3. Or, attach a service account to your Google Cloud resource.

# Example: Service Account setup
export SERVICE_ACCOUNT_PATH="/path/to/service-account.json"
export DRIVE_FOLDER_ID="your_folder_id_here"

# Example: OAuth 2.0 setup
export CREDENTIALS_PATH="/path/to/credentials.json"
export TOKEN_PATH="/path/to/token.json

# Example: Direct Injection (Base64)
export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."

Depending on your use case, you can run the server using uvx, local development mode, or Docker.

Using uvx (Recommended for Users)

This is the easiest method for most users. It fetches and runs the package temporarily.

For Development (Cloning the Repo)

If you need to modify the source code:

1. Clone the repository.
2. Set your authentication environment variables.
3. Run using uv run.

Using Docker (SSE transport)

To run the server in a container using SSE (Server-Sent Events) transport. It is recommended to use CREDENTIALS_CONFIG (Base64) in Docker to avoid mounting files.

# Quick Start with uvx
uvx mcp-google-sheets@latest

# Development mode
git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets
uv run mcp-google-sheets

# Docker (SSE on port 8000)
docker build -t mcp-google-sheets .
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