google-sheets-mcp

google-sheets-mcp

Google Sheets を MCP ツールとして使えます。下地にある数式を壊さずに、範囲を読み書きできます。

MCP を stdio 経由で扱う、単一の Go バイナリです。クライアントのサブプロセスとして、ご自身のマシン上で、ご自身の Google アカウントを使って実行します。ホストするサーバーも、共有デプロイも、サービスアカウントも必要ありません。Google OAuth クライアントを作成して一度ログインすれば、更新トークンは OS のキーチェーンに保存されます。

スプレッドシートの内部で動作します。ファイルの検索、共有、移動、ゴミ箱への移動、およびファイルのリビジョンは、Drive API を基盤とするサーバーの役割です。セルのコメントはこちらで扱い、セルのメモも扱います。

google-sheets-mcp を選ぶ理由

スプレッドシートでは、API 呼び出しのあとに取り消すことができません。また、目に見える値だけがセルのすべてとは限りません。数式や別の保存型、メモが隠れている場合があります。そのため、ここでの書き込みは信頼任せにせず、ガードされています。write_values はまず対象を読み取り、overwrite が指定されていなければ空でない値の上書きを拒否し、数式の上書きにはさらに overwrite_formulas が指定されていないと拒否します。そのたびに該当するセルを示します。また、入力時に Google のパーサーが変更した値はすべて報告されます。

インデックス計算も処理します。範囲はすべて A1 形式で、シート名は自動で引用符で囲まれます。アカウントの言語によって Google が最初のシートに付ける名前は異なるため、英語ではないこともよくあります。また、A1 形式を GridRange に変換する処理は、単一のパッケージにまとめられています。

スプレッドシートの内部で動作します。ファイルの検索、共有、移動、ゴミ箱への移動、およびファイルのリビジョンは、Drive API を基盤とするサーバーの役割です。セルのコメントはこちらで扱い、セルのメモも扱います。

読み取り、書き込み、書式設定、範囲に関連付けられたオブジェクト、gsheets:// リソース、永続的なアンカー、グラフ、ピボットテーブル、Connected Sheets のデータソース、セルのコメントに対応しています。 24 個のツールとその引数、返されるフィールドは安定しています。互換性を破る変更にはメジャーバージョンが必要で、ゲートがすべてのコミットを、最新リリースに記録されたインターフェイスと比較します。これを利用している MCP クライアントは 1 つであり、別のクライアントで信頼して使う前に把握しておくべき点です。経緯については docs/architecture.md の §16 をご覧ください。

インストール

go install github.com/mmedum/google-sheets-mcp/v3/cmd/google-sheets-mcp@latest

または、最新リリースからアーカイブ（Linux、macOS、Windows 向け、amd64 および arm64 対応）を入手し、実行前に検証してください。

sha256sum -c checksums.txt --ignore-missing

# The checksum file is signed with a keyless Sigstore certificate tied to
# the release workflow's identity. The bundle carries both.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp 'https://github\.com/mmedum/google-sheets-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And the archive itself carries build provenance.
gh attestation verify google-sheets-mcp_*.tar.gz --repo mmedum/google-sheets-mcp

すべてのアーカイブには SBOM も含まれているため、自分でビルドしていないバイナリの内容を確認できます。ビルドは再現可能です。-trimpath を使い、ビルド時刻ではなくコミットのタイムスタンプを使用するため、タグを再ビルドすると同じバイト列が得られます。

Claude Desktop

各リリースには .mcpb バンドルも含まれています。これを開くと Claude Desktop がサーバーをインストールし、OAuth クライアントの JSON を求めます。設定ファイルを編集する必要はありません。macOS、Windows、Linux のそれぞれで両方のアーキテクチャに対応しています。macOS ではユニバーサルバイナリ、Windows では amd64、Linux では起動時に適切なバイナリを選択する小さなランチャーを使用します。これは、バンドルのマニフェストにアーキテクチャを指定するキーがないためです。SHA-256 は同じ署名済みの checksums.txt に記載されています。

バンドルだけではログインできません。バイナリもインストールし、google-sheets-mcp login -secret <your client JSON> を一度実行してください。バンドルは同じ認証情報を使用します。Claude Code は .mcpb ファイルをインストールしないため、以下のコマンドを使用します。

Google のセットアップ

独自の OAuth クライアントが必要です。初回は約 15 分かかります。理由を含む手順は docs/gcp-setup.md で説明しています。概要と、doctor が確認する順番は次のとおりです。

1. Google Cloud プロジェクトを作成します。

2. Google Sheets API と Google Drive API を有効にします。後者は search_spreadsheets 用です。このサーバーが呼び出す Drive API はこれだけです。

3. 同意画面を設定します。Workspace アカウントの場合は Internal、個人アカウントの場合は External + Testing を選びます。後者では、Google がテスト中のアプリの更新トークンを期限切れにするため、毎週 login を再実行する必要があります。

4. login が要求する次の 2 つのスコープを追加します。

   スコープ	用途
   https://www.googleapis.com/auth/spreadsheets	このサーバーがスプレッドシート内で行うすべての操作
   https://www.googleapis.com/auth/drive.readonly	search_spreadsheets のみ

   Connected Sheets を使用する場合に限り、3 つ目のスコープを追加します。

   スコープ	用途
   https://www.googleapis.com/auth/bigquery.readonly	manage_data_source 用。GSHEETS_ENABLE_DATA_SOURCES=true の場合に限ります

   この設定が有効な場合にのみ login がこのスコープを要求するため、無効のままなら同意画面に表示されるのは上記の 2 つだけです。Google はこのスコープなしでは addDataSource を拒否し、「Please include bigquery.readonly scope」と表示するため、中途半端に動作する状態になって困ることはありません。

   drive や drive.file ではなく、意図的に drive.readonly を使用しています。このサーバーはスプレッドシートを検索しますが、ファイルの作成、移動、ゴミ箱への移動は行いません。より制限の厳しいスコープを使うことで、これは単なる約束ではなく保証になります。そのため、ライブドライバーは自身の後片付けもできません。

   GSHEETS_READ_ONLY=true の場合、login は最初のスコープの代わりに https://www.googleapis.com/auth/spreadsheets.readonly を要求し、書き込みツールは一切登録されません。

5. Desktop app タイプの OAuth 2.0 Client ID を作成し、JSON をダウンロードします。

次に、ログインします。

google-sheets-mcp login -secret ./client_secret.json

ログインすると認証 URL が表示され、続けてブラウザーを開こうとします。開けなかった場合も、URL はすでに画面に表示されています。コールバックは PKCE と state を使って、ランダムなポートで 127.0.0.1 に届きます。更新トークンは OS のキーリングに保存されます。キーリングがない場合は、設定ディレクトリ内の 0600 ファイルに保存され、その旨がコマンドから通知されます。

google-sheets-mcp status は、サインイン中のアカウントとトークンの保存先を表示します。google-sheets-mcp logout は Google でトークンを無効化し、ローカルのコピーを削除します。google-sheets-mcp doctor は認証情報、付与されたスコープ、Google からの実際の応答を確認し、不足しているものを示します。クライアント ID とアカウントはマスクされるため、出力を issue に貼り付けても安全です。

google-sheets-mcp status --json は、起動前にこのサーバーが設定済みかどうかを確認する必要があるスクリプト向けに、同じ状態を 1 つの JSON オブジェクトとして stdout に出力します。分岐に使うフィールドは credentials.configured です。schema_version が変わるのはフィールドが削除された場合、またはその意味が変わった場合だけです。アカウントはテキスト出力と同じように、ドメインだけがわかる形にマスクされます。人間向け出力のラベルはリリースごとに変更される可能性がありますが、オブジェクトは変更されません。

SSH 経由でのログイン

コールバックはリモートホストのループバックアドレスに届き、ブラウザーはローカルで動作するため、ポートを転送します。ポートはランダムに選ばれ、ログインの待機が始まってから一度だけ表示されるため、表示された URL から読み取ってください。127.0.0.1%3A<port> のようにパーセントエンコードされています。2 つ目のローカルターミナルで次を実行します。

ssh -N -L <port>:127.0.0.1:<port> user@remote-host

次に、URL をローカルで開きます。

クライアントを接続する

Claude Code：

claude mcp add google-sheets -- google-sheets-mcp

または、クライアントの設定ファイルに次のように記述します。

{
  "mcpServers": {
    "google-sheets": {
      "command": "google-sheets-mcp"
    }
  }
}

Claude Desktop は、独自の設定ファイルから同じ形式を読み込みます。アプリの PATH にバイナリが含まれていない場合は、バイナリの絶対パスを指定してください。

すべての設定は GSHEETS_* 環境変数で、同じ名前のフラグもあります。詳細は docs/configuration.md に記載されています。今知っておくとよい設定は3つです。GSHEETS_READ_ONLY=true は読み取り専用スコープを要求し、読み取りツールのみを登録します。GSHEETS_ENABLE_DESTRUCTIVE=true は、項目を削除する3つのツールを登録します。また、GSHEETS_PROFILE を使うと、1台のマシンで仕事用アカウントと個人用アカウントを使い分けられます。

ツール

ツールは24個あります。search_spreadsheets 以外はすべて Sheets スコープのみが必要です。読み取り専用モードでは、読み取りツールは代わりに spreadsheets.readonly を要求します。

ツール	機能	スコープ
get_spreadsheet	スプレッドシートのカードです。タイトル、リンク、ロケール、各シートの正確なタイトル、ID、サイズ、固定行、非表示状態と内容に加え、名前付き範囲、テーブル、保護された範囲、フィルタ表示を取得します。セルデータは取得しないため、10 個のセルがあるスプレッドシートでも 1,000 万個のセルがあるスプレッドシートでもコストは同じです。最初に呼び出してください	spreadsheets
read_range	指定範囲のグリッドを取得します。上部に列記号、左側に行番号が表示されます。show=both を指定すると、各値の下に、その値を生成した数式が表示されます。セル数と文字数に基づく予算制限があり、続きの取得にも対応しています。また、読み取りのたびにチェックポイントが返されます	spreadsheets
read_formatting	範囲の表示形式を取得します。数値形式、フォント、色、罫線、配置などを、セルごとではなく書式が同じセルのブロックごとに表示します。また、セル自体には設定されていなくても表示に影響する結合、条件付きルール、交互の背景色、入力規則、メモも取得します	spreadsheets
search_spreadsheets	タイトルの一部、内容のテキスト、所有者、または変更日時を指定してスプレッドシートを検索します。このサーバーが行う唯一の Drive 呼び出しです	drive.readonly
find_in_spreadsheet	1 つのスプレッドシートをテキストまたは RE2 パターンで検索し、A1 形式のアドレスを取得します。各一致が値、値の下にある数式、または隣にあるメモのどれで見つかったかも表示します	spreadsheets
create_spreadsheet	必要に応じて追加シートや初期値を設定し、新しいスプレッドシートを作成します。以降のすべての呼び出しで必要となる ID を含むカードを返します	spreadsheets
write_values	矩形範囲に値を書き込みます。まず、書き込みによって失われるもののうち、確認できないものがあれば書き込みを拒否し、その後、送信した値と異なる値を Google が保存した場合はすべて報告します	spreadsheets
append_rows	データのブロックの後ろに行を追加し、実際に追加された位置を報告します。追加先は Google が決定するため、同じシートでも指定する範囲によって追加位置が異なります	spreadsheets
format_cells	数値形式、フォント、色、罫線、配置、折り返し、結合、メモを、1 回のアトミックなバッチで適用します。結合、クリア、メモの追加の 3 つは既存のものを取り除く操作であり、確認されるまでそれぞれ拒否されます	spreadsheets
manage_range	範囲に関連付けられたものを追加、更新、削除します。対象は、名前付き範囲、保護された範囲、入力規則、テーブルとその列の種類、交互の背景色、条件付き書式ルール、カラースケールです。既存のものは ID ではなく、対象範囲で指定します	spreadsheets
transform_range	範囲の並べ替え、置換、空白の削除、重複の削除、分割、シャッフル、入力、コピー、移動を行います。データの新しいアドレスを指定せずにデータを移動する操作のため、それぞれの操作ではまず移動先の内容を読み取ります	spreadsheets
manage_anchor	行、列、シートにラベルを付け、スプレッドシートが編集されても再び見つけられるようにします。アンカーは挿入、削除、移動、並べ替えの際にも行を追跡します。一方、A1 アドレスは行が挿入された時点で古くなります。削除行を扱う 2 つのツールを含め、範囲または帯を指定する場所ではどこでも anchor:<name> を渡せます	spreadsheets
manage_chart	グラフとスライサーを追加、更新、移動、削除、一覧表示します。グラフはグリッドの上に配置されるため、追加しても既存の内容は上書きされません。グラフのデータは A1 形式で指定し、系列ごとに範囲を 1 つ指定します。一覧では、系列が失われたグラフも報告します。これはグラフに使われている列を削除した場合に起きますが、Sheets にはそれを知らせる機能がありません	spreadsheets
manage_pivot_table	日付または数値範囲によるグループ化、フィルタ、計算値を指定して、ピボットテーブルを追加、更新、削除、一覧表示します。列は A1 形式または見出しで指定し、番号で数えて指定することはできません。結果には、テーブルが現在占める矩形範囲が毎回表示されます。サイズはデータに基づいて計算され、任意に設定するものではありません。一覧では、各ルールをツールが受け付ける表記で読み取って返します	spreadsheets
manage_data_source	デフォルトでは無効です。Connected Sheets を通じて BigQuery データソースに接続し、更新、更新のキャンセル、接続内容の一覧表示を行います。get_spreadsheet は追加スコープなしで、そのスプレッドシートにデータソースがあるかどうかをすでに示します	spreadsheets、bigquery.readonly
read_cell_comments	スプレッドシートのセルにあるコメントスレッドを取得します。現在コメントが付いているセル、未解決か解決済みか、割り当て先、すべての投稿を確認できます。行が移動してもスレッドはセルを追跡します。また、行が削除されたスレッドもセルなしで一覧に表示されます	spreadsheets
manage_cell_comment	セルにコメントを付ける、返信する、投稿を編集する、解決する、再開する操作を行います。Google は割り当て先にメールを送信します。また、テキストで指定されたアドレスにも通知する場合があります。これにより、このサーバーはスプレッドシートの外部にいる相手にも連絡できます	spreadsheets
manage_sheet	シートの追加、名前変更、複製、別のスプレッドシートへのコピー、非表示、再表示、並べ替え、サイズ変更、固定、色の設定を行います	spreadsheets
edit_dimensions	行と列の挿入、移動、サイズ変更、自動サイズ調整、グループ化、グループ解除、非表示、再表示を行います	spreadsheets
delete_dimensions	破壊的な操作で、デフォルトでは無効です。削除対象の内容を数えたうえで、行または列とそのデータを削除します	spreadsheets
clear_values	破壊的な操作で、デフォルトでは無効です。範囲の値をクリアし、書式、メモ、入力規則は保持します	spreadsheets
delete_sheet	破壊的な操作で、デフォルトでは無効です。削除対象の内容を数えたうえで、シートとそのすべての内容を削除します	spreadsheets
delete_cell_comment	破壊的な操作で、デフォルトでは無効です。返信を含むコメントスレッド、または 1 件の返信を削除します。通常は削除ではなく解決する方法が適切です	spreadsheets
delete_data_source	破壊的な操作で、デフォルトでは無効です。Connected Sheets のデータソース、Google がそのために作成したシート、そのシート上のすべての内容を削除します。BigQuery スコープは不要なため、他のユーザーが接続したデータソースにもアクセスできます	spreadsheets
5 つの破壊的なツールは、GSHEETS_ENABLE_DESTRUCTIVE=true でない限り一切登録されません。また、それぞれの呼び出しには confirm: true が必要です。

クライアントが MCP の確認要求に対応している場合、サーバーはさらに、これら 5 つの操作の前、BigQuery データソースへの接続前、すべてのデータソースを一度に更新する前にも、ユーザー自身に確認を求めます。書き込みが実行されるのは「許可」を選んだ場合だけです。それ以外はすべて [blocked] になります。確認を求められないクライアントには何も表示されません。ただし、GSHEETS_REQUIRE_PROMPT=true の場合は、代わりにそれらの書き込みが拒否されます。

manage_data_source も、GSHEETS_ENABLE_DATA_SOURCES=true でない限り登録されません。また、この設定を有効にすると、login で 3 つ目のスコープが要求されます。Connected Sheets を利用するには、BigQuery が有効で課金が設定された Cloud プロジェクトが必要であり、利用開始前にそれらを用意する必要があるため、この設定はデフォルトで無効になっています。また、BigQuery へのアクセス許可を求める同意画面を表示するスプレッドシートサーバーは、ほとんどのユーザーにとって、利用していない製品へのアクセスを許可するよう求めていることになります。

リソース

スプレッドシートをツールで呼び出すのではなく、クライアントにアタッチする場合に使うリソースが 2 つあります。静的な一覧はありません。ユーザーのスプレッドシートを列挙するには Drive の一覧取得が必要であり、これは Drive API を基盤とするサーバーの役割です。また、Sheets API にはプッシュ通知も変更フィードもないため、サブスクリプションもありません。

URI	内容
gsheets://{spreadsheet}	カードです。各シートの正確なタイトル、ID、サイズに加え、名前付き範囲、テーブル、保護された範囲を表示します。セルは読み取りません
gsheets://{spreadsheet}/{sheet}	そのシートの使用範囲を CSV 形式で返します。シートに割り当てられたサイズではなく、何らかの値が入力されている行と列を対象とします。シートのタイトルはパーセントエンコードされます

安全性

見えていないものを、書き込みによって破壊することはありません。 Sheets には API 経由の元に戻す機能がないため、リクエストの作成前に拒否することだけが唯一の保護策です。空でないものを上書きするには overwrite が必要です。数式とその結果は読み取り時に同じように見えるため、数式を上書きするには overwrite_formulas も必要です。拒否時には、該当するセルと、処理を許可する引数がそれぞれ示されます。

同じ保護策は、フェーズ 2 で追加したすべての機能にも適用されます。以下は、想定ではなく、実際に気付かれないデータ損失を引き起こすと確認されたものです。

• 結合では、結合された各ブロックの左上の値が保持され、残りは破棄されます。レスポンスにはそのことが何も示されません。
• clear_format では、Sheets で元に戻せない書式が削除されます。
• メモの設定や削除では、値の読み取りでは確認できなかった内容が置き換えられます。
• 貼り付けや自動入力では、指定していないセルにもデータが入るため、貼り付け先の矩形範囲が読み取られ、ほかの対象と同じように保護されます。
• text_to_columns では、右隣の列にデータがあふれます。
• in_formulas を指定した find_replace では、セルに表示されている内容ではなく、セルの計算結果が書き換えられます。
• テーブルの削除では、その範囲に適用された条件付き書式ルールもすべて削除されます。これはライブ API で検証したもので、読み取りから確認できるものではありません。
• 行や列の削除では、その行や列にあるアンカーも削除されます。このことも、Google のレスポンスには一切記載されません。delete_dimensions は、削除前にアンカーを明示します。

保護策に加えて、以下の対策も講じています。

• 型変換は隠さず報告します。 input: typed では、人が入力する場合と同じように解析されるため、007 は 7 になり、2026-09-05 は日付になります。すべての書き込みで、Google に保存された値を読み戻して、変更された値をそれぞれ明示します。日付の場合は、セルに表示される内容も示すため、シリアル値がデータ損失のように見えることはありません。input: literal では送信した内容がそのまま保存されます。サーバーが一方を他方に置き換えることはありません。
• すべての書き込みで dry_run を利用できます。 Sheets には提案モードがないため、プレビューでは、何も送信せずに保護策で検出された内容と変更内容を報告します。利用可否はツールごとに宣言するのではなく、リフレクションによって判定されるため、このフラグを提供する書き込みがその指定を無視することはありません。
• 読み取り専用モードでは、書き込みツールが登録されません。 登録されていないツールは、クライアントの権限モードにかかわらず呼び出せません。設定はサーバーの起動時に行うため、1 回の呼び出しではなくセッション全体に適用されます。
• すべての読み取り結果にセル番地が表示されるため、モデルは数え直さずに、読み取った内容を書き戻せます。A1 が取り決めです。モデルが GridRange を見ることはなく、ゼロ始まりの半開区間による計算は、テーブルテストを備えた 1 つのパッケージにまとめられています。
• シート名は読み取るものであり、想定するものではありません。 Google ではアカウントの言語で最初のシート名が付けられるため、ポルトガル語のアカウントには Sheet1 が存在しません。どのツールもシートをデフォルトに設定せず、説明に例として示すこともありません。シートが見つからない場合は拒否し、実際に存在するシート名を示します。
• 読み取り量は呼び出し前に制限されます。 シートの実際の範囲に基づいてウィンドウを解決し、有限範囲を送信するため、終端を指定しない A:Z が列全体としてメモリに読み込まれることはありません。
• ログにペイロードは記録されません。 メソッド、ツール、結果、所要時間、短縮されたスプレッドシート ID が記録されます。セルの値、数式、タイトル、範囲、検索語句は記録されません。検索語句はリクエスト URL を通じてログに残る可能性があるため、トランスポートエラーからも取り除かれます。また、それらがログに含まれていればビルドが失敗するテストを設けています。

仕組み

MCP client ──stdio──► google-sheets-mcp
                       ├── tools     one handler per tool; one Kind decides its annotations
                       ├── service   the rules: resolve, budget, guard, report
                       ├── plan      typed batchUpdate requests, and the write guards
                       ├── grid      the server's view of a rectangle, and its checkpoints
                       ├── render    every word a caller reads
                       ├── a1        A1 notation ↔ GridRange, the only place that conversion lives
                       ├── gapi      REST client for Sheets and the one Drive call
                       └── auth      refresh token → access token

ヘルプの利用

問題が発生した場合は、google-sheets-mcp doctor を実行してください。認証情報、付与されたスコープ、Google からの実際の応答を確認し、不足しているものを示します。初回実行時の問題の多くは、API が有効になっていないか、自分が追加されていない同意画面が原因です。

原因がわからない場合は、 issue を作成してください。 issue にスプレッドシート ID や URL、セルの内容、 client_secret.json、トークンを貼り付けないでください。代わりに、どのようなものかを説明してください。 セキュリティ上の問題は、非公開で SECURITY.md に従って報告してください。

バージョン管理

ツール名と出力フィールドは、メジャーバージョン内で安定しています。新しいスコープ、再ログイン、クライアント設定でのコマンド変更など、対応が必要な変更には CHANGELOG.md で Breaking: と記載します。リリースノートもここから作成されます。

開発

make build     # the binary
make test      # race detector, coverage floor
make check     # everything CI runs

make check が完了の基準です。フォーマット、ビルドタグ付きコードを含む go vet、golangci-lint、パッケージごとのカバレッジ下限を設けたレーステスト、govulncheck、ライセンス許可リスト、2 種類のシークレットおよび識別子スキャン、stdio のスモークテスト、リリース済みツールのインターフェースとのスキーマ差分チェック、Claude Desktop バンドルのマニフェストにパッケージ対象のファイルのみが記載されていることの確認、Makefile と CI が同じ項目を実行することの確認、そして README、ドキュメント、変更履歴がコードと乖離した場合に失敗する鮮度チェックを実施します。

チェックに合格するだけでは十分ではありません。書き込み処理や API 応答の形式に触れる変更は、実際のアカウントで実行し、結果を数えるだけでなく、やり取りの記録を読みます。実行コマンドは docs/development.md に記載されています。

ドキュメント

• docs/architecture.md — リクエストの流れ、パッケージ構成、フェーズ計画、貢献者が元に戻すべきでない判断、API に対して確認した内容と、実際の API の挙動を記録した証拠ログ。
• docs/configuration.md — すべての設定。
• docs/development.md — ビルド、テスト、実際のアカウントを使った実行。
• docs/security.md — 脅威モデル。
• docs/runbook.md — 認証情報のローテーションや復旧。

貢献

質問やバグ報告は issues にお寄せください。プルリクエストも歓迎します。ブランチとレビューの流れについては CONTRIBUTING.md をご覧ください。make check に合格する必要があります。

セキュリティ

脆弱性の報告方法は SECURITY.md をご覧ください。

行動規範

CODE_OF_CONDUCT.md — Contributor Covenant 3.0。

ライセンス

Apache 2.0 — LICENSE をご覧ください。