sheets-write-mcp-server

Google Sheets への書き込み専用 MCP サーバー。google-sheets-mcp-server（読み取り専用）の対になる存在で、読み取りツールは持たない。読むだけなら readonly を使う。

設計思想

コミュニティ製の Sheets MCP は「アカウント内の全シートに読み書き可」という過剰権限になりがち。本サーバーは書き込みという破壊的操作を扱うため、全ツールが以下の安全パイプラインを通る：

whitelist（fail-closed）→ サイズ制限 → dry_run → 書込前スナップショット → 実行 → 監査ログ

• ホワイトリスト：~/.config/sheets-write-mcp/allowed_spreadsheets.yaml に登録された spreadsheet（さらに sheet 単位で絞り込み可）にしか書き込めない。ファイルが無い・壊れている場合は全拒否（fail-closed）。編集は即反映（再起動不要）
• dry_run：削除系ツール（clear_range / delete_rows / delete_columns / delete_sheet）はデフォルトで dry_run=true。実行計画と現在値のプレビューを返すだけで、明示的に dry_run=false を渡すまで何も起きない
• 書込前スナップショット：上書き・削除される値（数式は数式文字列のまま）を ~/.local/share/sheets-write-mcp/rollback/ に保存してから書き込む。スナップショット取得に失敗したら書き込みは実行されない。spreadsheet ごとに直近50世代
• 監査ログ：全操作（拒否・dry_run・エラー含む）を ~/.local/share/sheets-write-mcp/audit.jsonl に1行1レコードで記録
• サイズ制限：1回の操作で 5,000 セル超は force=true が必要
• 外部送信は Google APIs のみ。第三者サーバー経由なし

ロールバックの範囲

スナップショットが守るのは値と構造（行・列・シートの中身）。セル書式（色・罫線・条件付き書式等）の復元は対象外——書式事故は Google Sheets 本体の版履歴（ファイル > 変更履歴）で救済できるため、スナップショットの複雑化に見合わないと判断。schema_version フィールドがあるので将来拡張は可能。

ツール（18本・3層）

層	ツール	dry_run 既定
L1 値	update_range / batch_update_values / append_rows	false
L1 値	clear_range	true
L2 構造	insert_rows / insert_columns / add_sheet / duplicate_sheet / rename_sheet	false
L2 構造	delete_rows / delete_columns / delete_sheet	true
L3 装飾	set_number_format / set_cell_style / set_conditional_format / set_data_validation / set_basic_filter / protect_range	false

• 数式は既定で数式として解釈される（USER_ENTERED）。raw=true で文字列として格納
• シート指定は名前・gid どちらでも可
• L3 は指定した項目だけを fields マスクで更新（触っていない書式は保持）
• 対象外：ピボット・グラフ（将来）／スプレッドシート自体の作成・削除・共有（Drive API 管轄）／表示・ツール・拡張機能メニュー（API 非対応）

セットアップ

git clone <this repo> && cd sheets-write-mcp-server
python3 -m venv .venv && .venv/bin/pip install -e .

# 1. OAuth クライアント（readonly と同じものを使い回せる）
mkdir -p ~/.config/sheets-write-mcp
cp ~/.config/sheets-mcp/credentials.json ~/.config/sheets-write-mcp/

# 2. ホワイトリスト作成
cat > ~/.config/sheets-write-mcp/allowed_spreadsheets.yaml <<'EOF'
spreadsheets:
  - id: "<spreadsheet ID>"
    note: "（用途メモ）"
    writable_sheets: "*"        # または ["シート名", ...]
EOF

# 3. OAuth を一度通す（ブラウザが開く。token.json が書き込みスコープで生成される）
.venv/bin/python -c "from sheets_write_mcp.auth import _load_credentials; _load_credentials()"

トークンは readonly（spreadsheets.readonly）とは別ファイル・別スコープ（spreadsheets）。

Claude Code / Claude Desktop への登録

claude mcp add sheets-write -- /path/to/sheets-write-mcp-server/.venv/bin/sheets-write-mcp

Claude Desktop（claude_desktop_config.json）で readonly と並走：

{
  "mcpServers": {
    "sheets-readonly": { "command": "/path/to/sheets-mcp-server/.venv/bin/sheets-mcp" },
    "sheets-write":    { "command": "/path/to/sheets-write-mcp-server/.venv/bin/sheets-write-mcp" }
  }
}

環境変数

変数	デフォルト
SHEETS_WRITE_MCP_CREDENTIALS	~/.config/sheets-write-mcp/credentials.json
SHEETS_WRITE_MCP_TOKEN	~/.config/sheets-write-mcp/token.json
SHEETS_WRITE_MCP_WHITELIST	~/.config/sheets-write-mcp/allowed_spreadsheets.yaml
SHEETS_WRITE_MCP_DATA_DIR	~/.local/share/sheets-write-mcp/

開発

.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q       # 110+ tests
.venv/bin/python -m ruff check src/ tests/

grid.py（A1⇔GridRange 変換）が範囲計算の単一障害点。1-indexed（ユーザー向け）と 0-indexed（GridRange）の変換ミスは「隣の行を消す」事故に直結するため、境界値テストを最も厚くしている。

既知の制約

• スナップショットは valueRenderOption=FORMULA で取得するため、数式セルの計算結果値は保存されない（数式は保存され、復元時に再計算される）
• rename_sheet 後はホワイトリストのシート名指定が旧名のままになる——リネーム後に yaml を更新すること