Google Sheets MCP

Google Sheets MCP

日本語 | Русский

A1 Google Sheets MCP を使うと、AI アプリが自然な言葉で Google Sheets を操作できます。スプレッドシートの検索、データの読み取り、行の書き込みや追加、シートや書式の調整、グラフの作成、結果の共有ができます。

Google アカウントを使って Google Sheets API を利用します。読み取りと書き込みを分け、破壊的な操作を明示し、すべてのスプレッドシート操作が可能であるかのように示すのではなく、Sheets API の制限を明確にします。

• 26 個のツール。 スプレッドシートの検索と作成、範囲の読み取りと書き込み、シート、書式、データの入力規則、保護範囲、条件付き書式、構造化テーブル、グラフ、アクセス権を管理できます。
• 会話から接続できます。 「Google Sheets に接続して」と言うと、サーバーが OAuth クライアントの設定手順を案内し、PKCE を使って 127.0.0.1 への Google のリダイレクトを受け取り、トークンを自身で保持します。設定ファイルも再起動も必要ありません。
• 意図を確認してから書き込みます。 曖昧な失敗の後に書き込みを再実行することはありません。追加を再実行すると行が重複するためです。また、破壊的なツールには印が付いているので、AI クライアントが事前に確認できます。
• Sheets 専用です。 Drive はスプレッドシートの検索と共有のみに必要な内部依存関係です。汎用的な Drive ツールはなく、raw_request から Drive にアクセスすることもできません。
• Google スコープは最小限です。 spreadsheets ですべての Sheets ツールを利用できます。Drive スコープが必要なのは、スプレッドシートの検索と共有を行う場合だけです。

まずは読み取り専用の質問から始めましょう。

四半期予算のスプレッドシートを見つけて、各シートの内容を要約してください。

サーバーに接続 · ユースケースを見る · 技術ドキュメントを開く

1 分で動作を確認

あなた： 売上レポートのスプレッドシートの構成を見せてください。シート、それぞれのサイズ、固定されている行を確認したいです。

アシスタント： 各シートのサイズ、固定されているヘッダー、シート上のオブジェクトを表示します。何も変更されません。

あなた： 「February」を複製して「March」シートを用意し、レイアウトは維持したまま数値を消してください。

アシスタント： シートの複製、名前の変更、データ範囲のクリアという計画を提示し、変更する前に確認を求めます。

あなた： 確認します。

アシスタント： シートを複製し、値をクリアします。書式、データの入力規則、固定されている行は維持されます。

目次

• クイックスタート
• できること
• スプレッドシートの変更方法
• 変更できる内容
• アクセス権の取得
• 設定
• データ、制限、バックグラウンド処理
• 技術ドキュメント
• サポート

クイックスタート

Node.js 20+ と Google アカウントが必要です。インストール時に認証情報は不要です。サーバーは会話から接続します。

1. AI アプリにサーバーを追加します。
2. 「Google Sheets に接続して」と伝えます。アシスタントが、設定ファイルを編集することなく、OAuth クライアントの作成とアクセスの承認を案内します。
3. 上記の読み取り専用の質問をします。

codex mcp add google-sheets \
  -- npx -y @a1-x-tech/mcp-google-sheets@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-sheets \
  -- npx -y @a1-x-tech/mcp-google-sheets@latest

claude mcp list

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

{
  "servers": {
    "google-sheets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

依頼できること

データを検索して読み取る

• 名前に「budget」が含まれる最新のスプレッドシートを探し、その構成を表示します。
• 'Q3'!A1:F50 を読み取り、合計を要約します。
• Summary シートの数式を表示します。

数値を更新する

• 数式も含めて、この表を Sheet1!A1 に書き込みます。
• 今日の数値をログの新しい行として追加します。
• 複数の範囲を一括更新するか、書式を維持したまま下書きの範囲をクリアします。

整形して表示する

• 「March」シートを追加し、ヘッダー行を固定して太字にします。
• 条件付き書式で負の金額を赤くし、罫線を追加します。
• 月ごとの収益を示す縦棒グラフを専用のシートに作成します。
• データを構造化テーブルに変換し、データの入力規則を使ったドロップダウンを追加します。

保護して共有する

• 合計行を保護し、自分だけが編集できるようにします。
• 同僚に編集権限を付与し、ほかの全員には読み取り専用の権限を付与します。
• 現在このファイルにアクセスできるユーザーを表示します。

スプレッドシートに加わる変更

1. 値を操作するツールはセルを A1 表記（'Sheet name'!A1:C10）で指定し、構造を操作するツール（シート、書式設定、ルール、テーブル、グラフ）は 0 始まりのインデックスを持つ数値の sheetId で指定します。ID は get_spreadsheet で取得できます。シートのタイトルは指定先ではありません。
2. 書き込みでは対象範囲が上書きされます。append_values は最後のデータ行の後に行を追加します。null のセルはスキップされ、クリアされません。
3. clear_values は値と数式を消去しますが、書式設定、データの入力規則、メモ、結合は保持されます。API で元に戻すことはできません。シート、行、列を削除すると、そのデータは失われます。
4. バッチツールでは、複数の範囲やリクエストを 1 回の呼び出しにまとめられ、割り当て量に対して 1 回としてカウントされます。batchUpdate はアトミックで、すべてのリクエストが適用されるか、どれも適用されないかのいずれかです。

一部のスプレッドシート機能には専用ツールがありません。セルの結合、名前付き範囲、縞模様、フィルター、スライサー、検索と置換、グラデーションによる条件付き書式ルールは、Sheets API のオリジンに限定された raw_request を通じて操作します。新しいスプレッドシートはマイドライブのルートに作成されます。フォルダーへの移動には対応しておらず、manage_permissions ではオーナー権限を移譲できません。

変更できる内容

確認プロンプトは AI クライアントが制御します。サーバーは読み取り、書き込み、破壊的な操作を行うツールにそれぞれ印を付けるため、クライアントは内容の確認と実際の変更を区別できます。

アクセスの取得

Google Sheets には OAuth 2.0 が必要です。API キーだけでは利用できません。接続方法は 2 つあり、1 つ目は設定ファイルが不要です。

チャットから接続する（推奨）

「Google Sheets に接続して」と伝えると、アシスタントが一緒に手順を進めます。

1. setup_instructions でチェックリストが表示されます。Google Cloud プロジェクトを作成または選択し、Google Sheets API を有効にして、同意画面を設定し、デスクトップアプリの OAuth クライアントを作成します。
2. そのクライアントの JSON（「Download JSON」）をダウンロードし、アシスタントにそのパスを伝えます。set_client はファイルを所有者のみがアクセスできるように保存します。シークレットが会話を介して送信されることはありません。
3. start_login から Google の同意リンクが返されます。このマシンでリンクを開いて承認してください。コードはチャットを介さず、127.0.0.1 のワンショットリスナーに返されます（PKCE）。
4. finish_login がコードと交換し、トークンを ~/.config/mcp-google-sheets/credentials.json に保存します（モード 0600）。

トークンは呼び出しのたびに再読み込みされるため、すぐに接続が有効になり、AI アプリを再起動する必要はありません。auth_status で接続状況を確認でき、logout で接続を無効にしてトークンを削除できます。

環境変数（CI、自動インストール）

1. Google Cloud プロジェクトを作成または選択し、Google Sheets API を有効にします。スプレッドシートの検索と共有を行う場合は、Google Drive API も有効にしてください。

2. OAuth 同意画面を設定し、デスクトップアプリの OAuth クライアントを作成します。

3. スプレッドシートの所有者または編集権限を持つ Google アカウントを認証します。OAuth 2.0 Playground では、Use your own OAuth credentials を有効にすると、リフレッシュトークンを取得できます。

4. 必要最小限のスコープをリクエストします。

   https://www.googleapis.com/auth/spreadsheets
   

   これですべての Sheets ツールを利用できます。追加で Drive スコープが必要なのは search_spreadsheets と manage_permissions のみです。https://www.googleapis.com/auth/drive、検索のみの場合は drive.readonly、このアプリで作成したファイルの場合は drive.file を指定します。

テストモードの OAuth リフレッシュトークンは、7 日後に期限切れになる場合があります。長期的なアクセスが必要な場合は、OAuth アプリを公開するか、Workspace ドメイン内で内部アプリを使用してください。クライアントシークレットとリフレッシュトークンはパスワードとして扱ってください。

設定

すべての変数は省略可能です。どれも設定しなくても、サーバーはチャットから接続できます。

* OAuth 3 変数、またはアクセストークンのいずれかを指定してください。認証情報がなくてもサーバーは起動してツールを一覧表示します。最初の呼び出し時に、設定が必要な変数名が表示されます。

データ、制限、バックグラウンド処理

• リクエストは Google に送信されます。 ローカルサーバーは Google OAuth トークンを更新して Sheets API を呼び出します。また、スプレッドシートの検索と共有に限り、Drive API も呼び出します。匿名テレメトリに含まれるのは、インストール ID、パッケージのバージョン、AI クライアントとプラットフォームのバージョン、ツール名のみです。OAuth トークン、スプレッドシートのデータ、ツールの引数、プロンプトは含まれません。無効にするには ASKADS_TELEMETRY=0 を設定してください。
• Google には分単位のクォータがあります。 公開されている制限は、プロジェクトごとに毎分 300 回の読み取りと 300 回の書き込み、ユーザーごとにそれぞれ 60 回です。バッチ呼び出しは、含まれる範囲やリクエストの数にかかわらず 1 回として数えられます。スプレッドシートのセル数は最大 10,000,000 個です。429 が発生すると、サーバーはバックオフします。読み取りではネットワークエラーと 5xx エラーの後にも再試行しますが、失敗が確定できない書き込みは再実行しません。
• バックグラウンドでの定期ポーリングはありません。 サーバーは呼び出されたときだけ動作します。AI アプリがスケジュールされたタスクに対応していれば、定期的にスプレッドシートを確認できます。

技術ドキュメント

• MCP 機能カタログ — すべてのツールをタスク別に解説したページ。
• すべてのツールと入力
• 開発ドキュメント
• 公開ドキュメント
• Google Sheets API リファレンス

サポート

バグを見つけた場合や、実現したいシナリオがある場合は、イシューを作成するか、Telegram にご連絡ください。

最後まで読んでいただき、ありがとうございます！