google-sheets

Google Sheets

スタンドアロンの OAuth 認証を使用する、軽量な Google Sheets 連携機能です。MCP サーバーは不要です。読み取りと書き込みの両方に完全対応しています。

Google Workspace アカウントが必要です。 個人の Gmail アカウントには対応していません。

初回セットアップ

Google で認証します（ブラウザーが開きます）。

python scripts/auth.py login

認証状態を確認します。

python scripts/auth.py status

必要に応じてログアウトします。

python scripts/auth.py logout

読み取りコマンド

すべての操作は scripts/sheets.py で行います。ログインしていない場合は、初回使用時に自動で認証されます。

# Get spreadsheet content as plain text (default)
python scripts/sheets.py get-text SPREADSHEET_ID

# Get spreadsheet content as CSV
python scripts/sheets.py get-text SPREADSHEET_ID --format csv

# Get spreadsheet content as JSON
python scripts/sheets.py get-text SPREADSHEET_ID --format json

# Get values from a specific range (A1 notation)
python scripts/sheets.py get-range SPREADSHEET_ID "Sheet1!A1:D10"
python scripts/sheets.py get-range SPREADSHEET_ID "A1:C5"

# Find spreadsheets by search query
python scripts/sheets.py find "budget 2024"
python scripts/sheets.py find "sales report" --limit 5

# Get spreadsheet metadata (sheets, dimensions, etc.)
python scripts/sheets.py get-metadata SPREADSHEET_ID

書き込みコマンド

# Update a range of cells with values (JSON 2D array)
python scripts/sheets.py update-range SPREADSHEET_ID "Sheet1!A1:B2" '[["Hello","World"],["Foo","Bar"]]'

# Update with RAW input (no formula parsing, treats everything as literal text)
python scripts/sheets.py update-range SPREADSHEET_ID "Sheet1!A1:B1" '[["=SUM(A1:A5)","text"]]' --raw

# Append rows after the last data row
python scripts/sheets.py append-rows SPREADSHEET_ID "Sheet1!A:Z" '[["New Row Col A","New Row Col B"]]'

# Clear values from a range (keeps formatting)
python scripts/sheets.py clear-range SPREADSHEET_ID "Sheet1!A1:B10"

# Batch update (advanced - for formatting, merging, etc.)
python scripts/sheets.py batch-update SPREADSHEET_ID '[{"updateCells":{"range":{"sheetId":0},"fields":"userEnteredValue"}}]'

スプレッドシート ID

次のいずれかを使用できます。

• スプレッドシート ID：1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
• 完全な URL：https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit

スクリプトは URL から ID を自動的に抽出します。

出力形式

テキスト（デフォルト）

パイプ区切りの、人が読みやすい形式です。

Spreadsheet Title: Sales Data
Sheet Name: Q1
Name | Revenue | Units
Product A | 10000 | 50
Product B | 15000 | 75

CSV

後続の処理に適した標準的な CSV 形式です。

Name,Revenue,Units
Product A,10000,50
Product B,15000,75

JSON

構造化データ形式です。

{
  "Q1": [
    ["Name", "Revenue", "Units"],
    ["Product A", "10000", "50"]
  ]
}

A1 表記の例

• Sheet1!A1:B10 - Sheet1 の A1 から B10 までの範囲
• Sheet1!A:A - Sheet1 の A 列全体
• Sheet1!1:1 - Sheet1 の 1 行目全体
• A1:C5 - 最初のシートの範囲

値の入力オプション

• USER_ENTERED（デフォルト）：ユーザーが入力した場合と同様に値を解析します。数値、日付、数式が解釈されます。
• RAW（--raw フラグ）：値を指定されたとおりに保存します。数式や数値形式の解析は行われません。

トークン管理

トークンはシステムのキーリングを使用して安全に保存されます。

• macOS：Keychain
• Windows：Windows Credential Locker
• Linux：Secret Service API（GNOME Keyring、KDE Wallet など）

サービス名：google-sheets-skill-oauth

トークンの有効期限が切れると、Google のクラウド関数を使用して自動的に更新されます。