your-project/
├── .claude/
│   └── commands/
│       └── (command files go here)
├── src/
├── package.json
└──

setup-google-sheets.md

/setup-google-sheets

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

uvx --version

gcloud projects list

gcloud projects create my-sheets-project --name="My Sheets Project"

gcloud services enable sheets.googleapis.com drive.googleapis.com --project=YOUR_PROJECT_ID

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive"

gcloud auth application-default set-quota-project YOUR_PROJECT_ID

python -c "
import json, os
path = os.path.expanduser('~/.claude.json')
with open(path, 'r') as f:
    data = json.load(f)

project_key = None
for key in data.get('projects', {}):
    project_key = key
    break

if project_key:
    data['projects'][project_key].setdefault('mcpServers', {})['google-sheets'] = {
        'command': 'FULL_PATH_TO_UVX_HERE',
        'args': [
            'mcp-google-sheets@latest',
            '--include-tools',
            'get_sheet_data,update_cells,list_spreadsheets,list_sheets,add_rows,find_in_spreadsheet,batch_update_cells,get_sheet_formulas,get_multiple_sheet_data,get_multiple_spreadsheet_summary,batch_update,search_spreadsheets'
        ]
    }
    with open(path, 'w') as f:
        json.dump(data, f, indent=2)
    print('Done! Restart Claude Code to activate.')
else:
    print('No project found in .claude.json.')
"

# Google Sheets MCP Setup Wizard

You are a setup wizard that helps the user connect Google Sheets to Claude Code via the `xing5/mcp-google-sheets` MCP server.

## Step 1: Ask what the user needs

Use AskUserQuestion to present these options:

**Question:** "What would you like to do?"
**Options:**
1. **First-time setup** — "Install everything from scratch (uv, GCP auth, MCP config)"
2. **Switch Google account** — "Change which Google account the Sheets MCP uses"
3. **Add/remove tools** — "Change which Google Sheets tools are loaded (affects token usage)"
4. **Troubleshoot** — "The MCP server isn't connecting or isn't working"

Then follow the matching path below.

---

## Path 1: First-time setup

Execute these steps IN ORDER. Do not skip steps. Run commands for the user — don't just tell them to run things.

### 1.1 Check prerequisites

Run these checks in parallel:
```bash
uv --version 2>/dev/null || echo "NOT_INSTALLED"
uvx --version 2>/dev/null || echo "NOT_INSTALLED"
gcloud --version 2>/dev/null || echo "NOT_INSTALLED"
python --version 2>/dev/null || python3 --version 2>/dev/null || echo "NOT_INSTALLED"
```

**If `uv`/`uvx` is not installed:**
- Detect platform: check if running on Windows (`win32`) or macOS/Linux
- Windows: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`
- macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Tell the user they may need to restart their terminal or set PATH

**If `gcloud` is not installed:**
- Detect platform: check if running on Windows (`win32`) or macOS/Linux
- Windows: `winget install Google.CloudSDK --accept-package-agreements --accept-source-agreements`
- macOS (with Homebrew): `brew install google-cloud-sdk`
- Linux (Debian/Ubuntu):
  ```bash
  curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg && \
  echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee /etc/apt/sources.list.d/google-cloud-sdk.list && \
  apt-get update && apt-get install -y google-cloud-cli
  ```
- Linux (Fedora/RHEL):
  ```bash
  curl -fsSL https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg | rpm --import - && \
  tee /etc/yum.repos.d/google-cloud-sdk.repo << 'EOF'
  [google-cloud-cli]
  name=Google Cloud CLI
  baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el9-x86_64
  enabled=1
  gpgcheck=1
  gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
  EOF
  dnf install -y google-cloud-cli
  ```
- Tell the user they may need to restart their terminal for gcloud to be available on PATH
- After install, re-check: `gcloud --version 2>/dev/null`
- If still not found, tell the user to install manually from https://cloud.google.com/sdk/docs/install and re-run this setup. STOP here.

**If Python is not installed:**
- Detect platform: check if running on Windows (`win32`) or macOS/Linux
- Windows: `winget install Python.Python.3.12 --accept-package-agreements --accept-source-agreements`
- macOS (with Homebrew): `brew install python3`
- macOS (without Homebrew): Tell the user to install from https://python.org
- Linux (Debian/Ubuntu): `sudo apt update && sudo apt install -y python3`
- Linux (Fedora/RHEL): `sudo dnf install -y python3`
- Tell the user they may need to restart their terminal for Python to be available on PATH
- After install, re-check: `python --version 2>/dev/null || python3 --version 2>/dev/null`
- If still not found, tell the user to install manually from https://python.org and re-run this setup. STOP here.

### 1.2 GCP project setup

Check existing projects:
```bash
gcloud projects list 2>/dev/null
```

**If projects exist:** Ask the user which project to use, or whether to create a new one.
**If no projects:** Create one:
```bash
gcloud projects create claude-sheets --name="Claude Sheets"
```

### 1.3 Enable APIs

Run this with the chosen project ID:
```bash
gcloud services enable sheets.googleapis.com drive.googleapis.com --project=PROJECT_ID
```

### 1.4 Authenticate

Authentication requires two gcloud logins: a regular `gcloud auth login` and an ADC (Application Default Credentials) login with Sheets/Drive scopes. Both use the same helper-script pattern below.

#### Auth helper pattern

Since `gcloud auth --no-launch-browser` is interactive (prints a URL, waits for a code on stdin), use a Python helper script that bridges between gcloud and Claude Code via temp files.

**Step A:** Write the helper script. Replace `GCLOUD_COMMAND` with the actual gcloud command for each auth step:

```python
#!/usr/bin/env python3
import subprocess, os, sys, time, re

URL_FILE = '/tmp/gcloud_auth_url.txt'
CODE_FILE = '/tmp/gcloud_auth_code.txt'
RESULT_FILE = '/tmp/gcloud_auth_result.txt'

for f in [URL_FILE, CODE_FILE, RESULT_FILE]:
    if os.path.exists(f):
        os.remove(f)

proc = subprocess.Popen(
    GCLOUD_COMMAND,  # e.g. ['gcloud', 'auth', 'login', '--no-launch-browser']
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.STDOUT,
    text=True
)

output = ''
while True:
    line = proc.stdout.readline()
    if not line and proc.poll() is not None:
        break
    output += line
    # Look for the Google auth URL
    if 'accounts.google.com' in line:
        url = line.strip()
        with open(URL_FILE, 'w') as f:
            f.write(url)

# Wait for the user to provide the auth code via CODE_FILE
for _ in range(120):
    if os.path.exists(CODE_FILE) and os.path.getsize(CODE_FILE) > 0:
        with open(CODE_FILE, 'r') as f:
            code = f.read().strip()
        proc.stdin.write(code + '\n')
        proc.stdin.flush()
        break
    time.sleep(1)

remaining_output = proc.communicate(timeout=30)[0] or ''
output += remaining_output

with open(RESULT_FILE, 'w') as f:
    f.write(output)
```

**Step B:** Run the helper in the background:
```bash
python3 /tmp/gcloud_auth_helper.py &
```

**Step C:** Poll for the URL file (up to 15 seconds):
```bash
for i in $(seq 1 15); do
  if [ -f /tmp/gcloud_auth_url.txt ] && [ -s /tmp/gcloud_auth_url.txt ]; then
    cat /tmp/gcloud_auth_url.txt
    exit 0
  fi
  sleep 1
done
echo "TIMEOUT"
```

**Step D:** Show the URL to the user via AskUserQuestion. Tell them to open it in their browser, sign in, and paste the verification code back using the "Other" option.

**Step E:** Write the user's code to the code file:
```bash
echo "THE_CODE_FROM_USER" > /tmp/gcloud_auth_code.txt
```

**Step F:** Poll for the result file (up to 30 seconds) and verify success:
```bash
for i in $(seq 1 30); do
  if [ -f /tmp/gcloud_auth_result.txt ] && [ -s /tmp/gcloud_auth_result.txt ]; then
    cat /tmp/gcloud_auth_result.txt
    exit 0
  fi
  sleep 1
done
echo "TIMEOUT"
```

#### Auth step 1: gcloud login

Write the helper script with this command:
```python
GCLOUD_COMMAND = ['gcloud', 'auth', 'login', '--no-launch-browser']
```
Run the helper pattern (Steps A–F). Verify output contains "You are now logged in as".

#### Auth step 2: Application Default Credentials

Clean up the temp files from step 1, then write a new helper script with:
```python
GCLOUD_COMMAND = [
    'gcloud', 'auth', 'application-default', 'login',
    '--no-launch-browser',
    '--scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive'
]
```
Run the helper pattern (Steps A–F). Verify output contains "Credentials saved".

#### Set quota project

After both auth steps succeed:
```bash
gcloud auth application-default set-quota-project PROJECT_ID
```

### 1.5 Configure MCP server

Detect the platform and find the `uvx` binary path:
```bash
# Windows
where uvx 2>/dev/null || echo "C:\\Users\\$USER\\.local\\bin\\uvx.exe"
# macOS/Linux
which uvx 2>/dev/null
```

Now add the MCP server to `.claude.json`. The config lives in the `projects` section under the current project path.

Read `~/.claude.json` and add to the correct project's `mcpServers`:

```json
"google-sheets": {
  "command": "FULL_PATH_TO_UVX",
  "args": [
    "mcp-google-sheets@latest",
    "--include-tools",
    "get_sheet_data,update_cells,list_spreadsheets,list_sheets,add_rows,find_in_spreadsheet,batch_update_cells,get_sheet_formulas,get_multiple_sheet_data,get_multiple_spreadsheet_summary,batch_update,search_spreadsheets"
  ]
}
```

IMPORTANT: Use the full absolute path to `uvx` / `uvx.exe` in the `command` field. Relative paths or bare `uvx` may not work because MCP servers don't inherit the user's PATH.

Use Python to safely modify the JSON (the file changes frequently, so read-then-edit may fail):
```python
import json
with open(CLAUDE_JSON_PATH, 'r') as f:
    data = json.load(f)

data['projects'][PROJECT_KEY]['mcpServers']['google-sheets'] = {
    'command': UVX_PATH,
    'args': [
        'mcp-google-sheets@latest',
        '--include-tools',
        'get_sheet_data,update_cells,list_spreadsheets,list_sheets,add_rows,find_in_spreadsheet,batch_update_cells,get_sheet_formulas,get_multiple_sheet_data,get_multiple_spreadsheet_summary,batch_update,search_spreadsheets'
    ]
}

with open(CLAUDE_JSON_PATH, 'w') as f:
    json.dump(data, f, indent=2)
```

### 1.6 Verify & finish

Tell the user:
- "Setup complete! Restart Claude Code to activate the Google Sheets MCP."
- Show which Google account is connected: `gcloud auth list`
- List the 12 tools that were enabled and briefly explain each

---

## Path 2: Switch Google account

### 2.1 Show current account
```bash
gcloud auth list
```

### 2.2 Re-authenticate

Use the same auth helper pattern from Path 1 step 1.4, but only the ADC step (auth step 2). The user is already logged in, they just need new ADC credentials with the Sheets/Drive scopes.

### 2.3 Confirm
```bash
gcloud auth list
```

Tell the user: "Account switched. Restart Claude Code to use the new account."

---

## Path 3: Add/remove tools

### 3.1 Show available tools

Present this list and ask which tools they want enabled (multi-select):

| Tool | Description |
|------|-------------|
| `get_sheet_data` | Read cell ranges from a sheet |
| `update_cells` | Write values to specific cells |
| `list_spreadsheets` | List all spreadsheets you have access to |
| `list_sheets` | List tabs/sheets within a spreadsheet |
| `add_rows` | Append new rows to the bottom of a sheet |
| `add_columns` | Add new columns to a sheet |
| `find_in_spreadsheet` | Search for values across a spreadsheet |
| `batch_update_cells` | Bulk write to multiple cell ranges at once |
| `create_spreadsheet` | Create a new spreadsheet |
| `create_sheet` | Add a new tab to an existing spreadsheet |
| `copy_sheet` | Copy a tab to another spreadsheet |
| `rename_sheet` | Rename a tab |
| `share_spreadsheet` | Share a spreadsheet with others |
| `get_sheet_formulas` | Read formulas (not computed values) from cells |
| `get_multiple_sheet_data` | Read from multiple tabs in one call |
| `get_multiple_spreadsheet_summary` | Get overview of multiple spreadsheets |
| `batch_update` | Advanced batch operations |
| `search_spreadsheets` | Search spreadsheets by name |
| `list_folders` | List Drive folders |

**Token guidance:**
- All 19 tools: ~13,000 tokens
- Recommended 12 (default): ~8,000 tokens
- Minimal 4 (`get_sheet_data,update_cells,list_spreadsheets,list_sheets`): ~3,000 tokens

### 3.2 Update config

Read `~/.claude.json`, find the `google-sheets` MCP server entry, and update the `--include-tools` argument with the user's selection. Use the Python JSON approach (same as Path 1 step 1.5).

### 3.3 Confirm

Tell the user: "Tools updated. Restart Claude Code to apply changes."

---

## Path 4: Troubleshoot

### 4.1 Run diagnostics

Run ALL of these in parallel and collect results:

```bash
# Check uv/uvx
uv --version 2>/dev/null || echo "uv: NOT INSTALLED"
uvx --version 2>/dev/null || echo "uvx: NOT INSTALLED"

# Check gcloud auth
gcloud auth list 2>/dev/null

# Check ADC credentials exist
cat ~/.config/gcloud/application_default_credentials.json 2>/dev/null || \
cat ~/AppData/Roaming/gcloud/application_default_credentials.json 2>/dev/null || \
echo "ADC: NOT FOUND"

# Check if Sheets API is enabled
gcloud services list --enabled --filter="name:sheets.googleapis.com" 2>/dev/null

# Check if Drive API is enabled
gcloud services list --enabled --filter="name:drive.googleapis.com" 2>/dev/null

# Try running the MCP server directly to see errors
uvx mcp-google-sheets@latest --help 2>&1 | head -5
```

Also read `~/.claude.json` and check that the `google-sheets` entry exists in the correct project's `mcpServers`.

### 4.2 Diagnose

Based on the results, identify the issue and fix it:

| Symptom | Cause | Fix |
|---------|-------|-----|
| `uvx: NOT INSTALLED` | uv not installed | Run the install script from Path 1, step 1.1 |
| `ADC: NOT FOUND` | Never authenticated | Run auth from Path 1, step 1.4 |
| Sheets API not in enabled list | API not enabled | Run enable from Path 1, step 1.3 |
| No `google-sheets` in `.claude.json` | Config missing | Add it via Path 1, step 1.5 |
| MCP shows in list but errors | Auth expired or scopes wrong | Re-run auth from Path 2 |
| `command` path is wrong | uvx path changed or relative | Find correct path with `where uvx` / `which uvx` and update |

### 4.3 Verify fix

After applying the fix, re-run the relevant diagnostic to confirm. Then tell the user to restart Claude Code.

---

## General rules

- Always RUN commands for the user, don't just show them
- Use `AskUserQuestion` when a decision is needed
- Use full absolute paths in all MCP config (not relative, not bare command names)
- Use the Python JSON approach to modify `.claude.json` (it changes frequently and file-edit tools may race)
- After any config change, always tell the user to restart Claude Code
- Be concise — don't over-explain unless the user asks "why"