# google-sheets-mcp

![Python](https://img.shields.io/badge/python-3.11+-blue.svg)
![MCP](https://img.shields.io/badge/MCP-1.26+-green.svg)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://console.cloud.google.com/)
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](https://docs.astral.sh/uv/) (recommended) or pip

## Installation

### Using uv (recommended)

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

### Using pip

```bash
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:

```env
# 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:

```bash
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`

```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

```bash
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