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

Related MCP server: Google Sheets MCP Server

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.

write_cells

Write values to a cell range.

append_rows

Append rows to the end of data in a sheet.

create_spreadsheet

Create a new Google Spreadsheet.

list_sheets

List all sheet tabs in a spreadsheet.

clear_cells

Clear cell values (formatting is preserved).

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