MCP Directory

How to add mcp-google-sheets to Windsurf

Your AI assistant's gateway to Google Sheets — read, write, format, and chart spreadsheets via MCP. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 912★ · stdio · oauth

Windsurf config for mcp-google-sheets

uvx mcp-google-sheets@latest
{
  "mcpServers": {
    "mcp-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"
      }
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the mcp-google-sheets config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5mcp-google-sheets's tools become available to Cascade.

Before you start

  • A Google Cloud Platform project with the Google Sheets API and Google Drive API enabled
  • Google credentials: a Service Account JSON key (recommended), OAuth 2.0 client credentials, or Application Default Credentials
  • uv / uvx installed (fast Python package installer), or Python with the package installed
  • For Service Account use: a Google Drive folder shared with the service account email (DRIVE_FOLDER_ID)

What mcp-google-sheets can do in Windsurf

list_spreadsheets

Lists spreadsheets in the configured Drive folder (Service Account) or accessible by the user (OAuth); optional folder_id.

create_spreadsheet

Creates a new spreadsheet with a given title and optional target Drive folder; returns spreadsheetId, title, and folder.

get_sheet_data

Reads data from a range in a sheet/tab (A1 notation); can return values only or full grid data with formatting/metadata.

get_sheet_formulas

Reads cell formulas from a range in a sheet/tab as a 2D array.

update_cells

Writes a 2D array of values to a specific A1-notation range, overwriting existing data.

batch_update_cells

Updates multiple ranges in a single API call via a map of range strings to 2D value arrays.

add_rows

Inserts empty rows into a sheet/tab at a specified 0-based start index.

add_columns

Inserts empty columns into a sheet/tab at a specified 0-based start index.

Security

Requires Google Cloud credentials with access to the Google Sheets and Google Drive APIs. A Service Account is recommended; store its JSON key file securely and share only the intended Drive folder with the service account's email. For container/CI environments, prefer injecting Base64-encoded credentials via the CREDENTIALS_CONFIG env var rather than mounting key files. OAuth tokens are written to TOKEN_PATH, which must be writable. Granting the service account broad roles (e.g. Editor) gives the server wide access to your spreadsheets, so scope permissions appropriately.

mcp-google-sheets + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the mcp-google-sheets config there under the "mcpServers" key and restart the client.

Is mcp-google-sheets safe to use with Windsurf?

Requires Google Cloud credentials with access to the Google Sheets and Google Drive APIs. A Service Account is recommended; store its JSON key file securely and share only the intended Drive folder with the service account's email. For container/CI environments, prefer injecting Base64-encoded credentials via the CREDENTIALS_CONFIG env var rather than mounting key files. OAuth tokens are written to TOKEN_PATH, which must be writable. Granting the service account broad roles (e.g. Editor) gives the server wide access to your spreadsheets, so scope permissions appropriately.

How do I run the server?

Install uv, set your Google credential environment variables, then run `uvx mcp-google-sheets@latest`. Most MCP clients (e.g. Claude Desktop) can launch the server for you via the config block.

Which authentication methods are supported?

Four: Service Account (recommended, via SERVICE_ACCOUNT_PATH), OAuth 2.0 (interactive, via CREDENTIALS_PATH/TOKEN_PATH), direct Base64 credential injection (CREDENTIALS_CONFIG, ideal for Docker/CI), and Application Default Credentials (ADC). The server checks them in priority order.

Can I reduce the context tokens it consumes?

Yes. By default all 19 tools are enabled (~13K tokens). Use the `--include-tools` command-line flag or the `ENABLED_TOOLS` environment variable with a comma-separated list to expose only the tools you need.

View repo Full mcp-google-sheets page