@node2flow/google-sheets-mcp

MCP server for Google Sheets — read, write, format, and manage spreadsheets through 23 tools via the Model Context Protocol.

Quick Start

Claude Desktop / Cursor

Add to your MCP config:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@node2flow/google-sheets-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

HTTP Mode

GOOGLE_CLIENT_ID=xxx GOOGLE_CLIENT_SECRET=xxx GOOGLE_REFRESH_TOKEN=xxx npx @node2flow/google-sheets-mcp --http

MCP endpoint: http://localhost:3000/mcp

Cloudflare Worker

Available at: https://google-sheets-mcp-community.node2flow.net/mcp

POST https://google-sheets-mcp-community.node2flow.net/mcp?GOOGLE_CLIENT_ID=xxx&GOOGLE_CLIENT_SECRET=xxx&GOOGLE_REFRESH_TOKEN=xxx

Tools (23)

Spreadsheet (2)

| Tool | Description | |------|-------------| | gs_create_spreadsheet | Create a new spreadsheet with title and optional sheets | | gs_get_spreadsheet | Get metadata — sheet names, IDs, properties |

Values (6)

| Tool | Description | |------|-------------| | gs_read_values | Read cell values from an A1 range | | gs_batch_read | Read multiple ranges at once | | gs_write_values | Write values to a range (2D array) | | gs_append_values | Append rows after existing data | | gs_clear_values | Clear values in a range (keeps formatting) | | gs_batch_write | Write to multiple ranges at once |

Sheet Management (5)

| Tool | Description | |------|-------------| | gs_add_sheet | Add a new sheet/tab | | gs_delete_sheet | Delete a sheet/tab (irreversible) | | gs_rename_sheet | Rename a sheet/tab | | gs_copy_sheet | Copy sheet to another spreadsheet | | gs_duplicate_sheet | Duplicate sheet within same spreadsheet |

Formatting (4)

| Tool | Description | |------|-------------| | gs_format_cells | Bold, italic, colors, font, alignment, number format | | gs_merge_cells | Merge cells in a range | | gs_unmerge_cells | Unmerge cells | | gs_auto_resize | Auto-fit column widths or row heights |

Data Operations (4)

| Tool | Description | |------|-------------| | gs_sort_range | Sort range by column | | gs_find_replace | Find and replace text (supports regex) | | gs_set_basic_filter | Set or clear auto-filter on a sheet | | gs_add_protected_range | Protect a range from editing |

Advanced (2)

| Tool | Description | |------|-------------| | gs_add_chart | Add a chart (bar, line, column, scatter, etc.) | | gs_batch_update | Raw batchUpdate for any operation |

A1 Notation

Ranges use A1 notation for the Values tools:

Sheet1!A1:C10    — specific range in Sheet1
Sheet1           — entire sheet
A:C              — columns A through C (first sheet)
Sheet1!A1:A      — column A, all rows
Sheet1!1:5       — rows 1 through 5

Index Notation

Formatting and batchUpdate tools use 0-based indices:

Row 1    → index 0      Column A → index 0
Row 2    → index 1      Column B → index 1
Row 10   → index 9      Column Z → index 25

Ranges are inclusive start, exclusive end:

• startRowIndex: 0, endRowIndex: 5 = rows 1-5
• startColumnIndex: 0, endColumnIndex: 3 = columns A-C

Configuration

| Parameter | Required | Description | |-----------|----------|-------------| | GOOGLE_CLIENT_ID | Yes | OAuth 2.0 Client ID from Google Cloud Console | | GOOGLE_CLIENT_SECRET | Yes | OAuth 2.0 Client Secret | | GOOGLE_REFRESH_TOKEN | Yes | Refresh token (obtained via OAuth consent flow) |

Getting Your Credentials

1. Go to Google Cloud Console
2. Create a project → Enable Google Sheets API
3. Create OAuth 2.0 Client ID (Desktop app type)
4. Use the OAuth Playground or your app to get a refresh token with scope https://www.googleapis.com/auth/spreadsheets

OAuth Scopes

| Scope | Access | |-------|--------| | spreadsheets | Full read/write access | | spreadsheets.readonly | Read-only access |

License

MIT