google-sheets-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
5. 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