google-sheets-mcp

google-sheets-mcp

!Python !MCP

A Model Context Protocol (MCP) server that lets Claude interact with Google Sheets — read, write, append, create, and clear spreadsheet data using natural language.

Features

| Tool | Description | |------|-------------| | read_cells | Read cell values from a spreadsheet (single cell, range, or entire sheet) | | write_cells | Write values to a cell range | | append_rows | Append rows to the end of a sheet | | create_spreadsheet | Create a new spreadsheet with custom sheet tabs | | list_sheets | List all sheet tabs in a spreadsheet | | clear_cells | Clear cell values while preserving formatting |

Prerequisites

1. Google Cloud Setup

1. Go to Google Cloud Console
2. Create a project (or select an existing one)
3. Enable the Google Sheets API: APIs & Services → Library → search "Google Sheets API" → Enable
4. Create OAuth 2.0 credentials:

• APIs & Services → Credentials → + Create Credentials → OAuth client ID
• Application type: Desktop app
• Name: google-sheets-mcp (or any name)
• Click Create → Download JSON

1. Save the downloaded file as credentials/client_secret.json

Important: Make sure to select Desktop app as the application type. Web application credentials will cause a redirect_uri_mismatch error.

2. Requirements

• Python 3.11+
• uv (recommended) or pip

Installation

Using uv (recommended)

git clone https://github.com/takehirokawaguchi/google-sheets-mcp.git
cd google-sheets-mcp
uv sync

Using pip

git clone https://github.com/takehirokawaguchi/google-sheets-mcp.git
cd google-sheets-mcp
pip install -e .

Configuration

Create a .env file in the project root:

# Path to your OAuth2 client secret JSON (required)
GOOGLE_OAUTH_CLIENT_SECRET_FILE=/path/to/google-sheets-mcp/credentials/client_secret.json

# Path to token cache file (optional, defaults to ~/.config/google-sheets-mcp/token.json)
# GOOGLE_OAUTH_TOKEN_FILE=/path/to/token.json

First-time authentication

Run the server once to complete the OAuth2 flow in your browser:

uv run google-sheets-mcp

A browser window will open asking you to sign in to your Google account and grant access to Google Sheets. After authorization, the token is cached at ~/.config/google-sheets-mcp/token.json and subsequent runs will not require browser interaction.

Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/google-sheets-mcp",
        "google-sheets-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRET_FILE": "/path/to/google-sheets-mcp/credentials/client_secret.json"
      }
    }
  }
}

Restart Claude Desktop after saving the configuration. The Google Sheets tools will then be available in your conversations.

Example prompts

Read the data from Sheet1 of my spreadsheet (ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms)

Append a new row with ["Alice", 30, "Tokyo"] to the "Users" sheet

Create a new spreadsheet called "Q1 Budget" with sheets: Overview, Jan, Feb, Mar

MCP Tools Reference

read_cells

Read cell values from a Google Spreadsheet.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | spreadsheet_id | string | yes | — | Spreadsheet ID from the URL | | range | string | yes | — | A1 notation range, e.g. Sheet1!A1:D5 | | value_render | string | no | FORMATTED_VALUE | FORMATTED_VALUE / UNFORMATTED_VALUE / FORMULA |

write_cells

Write values to a cell range.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | spreadsheet_id | string | yes | — | Spreadsheet ID | | range | string | yes | — | A1 notation range, e.g. Sheet1!A1:C2 | | values | array | yes | — | 2D array of values, e.g. [["Name", "Age"], ["Alice", 30]] | | value_input | string | no | USER_ENTERED | USER_ENTERED (parse formulas) / RAW (literal strings) |

append_rows

Append rows to the end of data in a sheet.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | spreadsheet_id | string | yes | — | Spreadsheet ID | | sheet_name | string | yes | — | Sheet tab name, e.g. Sheet1 | | values | array | yes | — | 2D array of rows to append | | value_input | string | no | USER_ENTERED | USER_ENTERED / RAW | | insert_data_option | string | no | INSERT_ROWS | INSERT_ROWS / OVERWRITE |

create_spreadsheet

Create a new Google Spreadsheet.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | title | string | yes | — | Title of the new spreadsheet | | sheet_names | array | no | ["Sheet1"] | List of sheet tab names to create |

list_sheets

List all sheet tabs in a spreadsheet.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | spreadsheet_id | string | yes | Spreadsheet ID |

clear_cells

Clear cell values (formatting is preserved).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | spreadsheet_id | string | yes | Spreadsheet ID | | range | string | yes | A1 notation range to clear, e.g. Sheet1!A1:Z100 |

Development

Run tests

uv run pytest -v

Project structure

google-sheets-mcp/
├── src/
│   └── google_sheets_mcp/
│       ├── auth.py           # OAuth2 authentication
│       ├── sheets_client.py  # Google Sheets API wrapper
│       ├── server.py         # MCP tool definitions (FastMCP)
│       └── __main__.py       # Entry point
├── tests/
│   ├── conftest.py
│   ├── test_auth.py
│   ├── test_sheets_client.py
│   └── test_server.py
├── credentials/              # Place client_secret.json here (git-ignored)
└── pyproject.toml

License

MIT