mcp-google-sheets-full

mcp-google-sheets-full

Sheets API でできることをすべて実行できる Google Sheets MCP サーバーです。

読み取り／書き込み、構造変更用の batchUpdate、Drive 検索、そして任意の Node.js コードを実行するエスケープハッチ（run_sheets_script）を含む、26 個のツールを備えています。sheets／drive／auth／spreadsheetId はあらかじめ注入されています。認証モードは 2 種類です。OAuth（デフォルト。自分の Google アカウントを使用し、シートごとの設定は不要）またはサービスアカウント（オプトイン。ヘッドレス実行／CI 向け）です。

このサーバーを選ぶ理由

ほとんどの Google Sheets MCP サーバーは、厳選された操作だけを公開し、それ以上は対応していません。想定されていない操作（特定の条件付き書式設定リクエスト、複数ステップの移行、Drive 側の操作、分析してから書き込むワークフローなど）が必要になると、行き詰まってしまいます。

このサーバーは、不足している基本機能として**run_sheets_script**を追加します。Node.js のコードスニペットを渡すと、結果が返されます。Sheets v4 と Drive v3 のクライアントは認証済みで、すでにスコープ内にあります。一時ファイルは必ず削除されます。

	mcp-google-sheets-full	freema/mcp-gsheets	xing5/mcp-google-sheets	ringo380/claude-google-sheets-mcp
読み取り／書き込み／追記／クリア	✅	✅	✅	✅
構造変更用の batchUpdate（生のリクエスト）	✅	一部対応	❌	❌
タブ／行／書式／罫線の詳細操作	✅	✅	一部対応	❌
Drive 検索（list／search_spreadsheets）	✅	❌	一部対応	❌
任意のコード実行（run_sheets_script）	✅	❌	❌	❌
認証モード	✅ OAuth がデフォルト＋サービスアカウントをオプトイン	サービスアカウント優先	両方	両方
言語	TypeScript／Node	TypeScript／Node	Python	Python

spreadsheetId は、すべてのツールで必ず明示的なパラメーターとして指定します。暗黙のデフォルト値はありません。

セキュリティモデル

run_sheets_script は、MCP サーバーが実行されているマシン上で、ユーザーアカウントを使い、OAuth トークンで認証して Node.js コードを実行します。信頼境界は、Claude がユーザーに代わってコードを実行できるようにする他のツール（Bash、Edit、Write）と同じです。

• スクリプトで実行できるのは、OAuth スコープ（Sheets ＋ Drive）で許可された操作に限られます。他の Google サービス、tmpdir 外のファイルシステム、またはホストの Node プロセスで許可されていないネットワーク操作にはアクセスできません。
• スクリプトごとに os.tmpdir() 内に新しい一時ファイルが作成され、node 経由で実行されます。完了時（成功時、失敗時とも）に削除されます。
• 呼び出しごとにタイムアウトがあります（デフォルトは 2 分、最大 10 分）。
• トークンがディスク外に出ることはありません。OAuth ファイルは ~/.mcp-google-sheets/ に保存されます。

コード実行に不安がある場合は、run_sheets_script を呼び出さないでください。他の 25 個のツールで、一般的な用途に対応できます。

AI エージェント向け

ユーザーのためにこのサーバーをインストールまたは運用する AI エージェント（Claude Code、Cursor など）の場合は、AGENTS.md をお読みください。標準的な手順に沿ったセットアップフロー、ツール選択ガイド、よくある失敗例、信頼とセキュリティに関する注意事項が記載されています。

セットアップ（初回のみ）

1. インストール

npm install -g mcp-google-sheets-full

これにより、mcp-google-sheets-full 実行ファイルが PATH に配置されます。更新するには、同じコマンドを再実行してください。削除するには、npm uninstall -g mcp-google-sheets-full を実行してください。

開発する場合は、リポジトリをクローンして npm install && npm run build を実行します。

2. 認証モードを選択

サーバーを認証する方法は 2 つあります。使用方法に応じて、いずれか 1 つだけ選択してください。

	OAuth（デフォルト）	サービスアカウント
最適な用途	ノート PC 上の Claude Desktop／Code／Cursor	CI、cron、サーバーレス、ヘッドレス自動化
セットアップの手間	~/.mcp-google-sheets/ に 1 ファイル	任意の場所に 1 ファイル ＋ 1 つの環境変数
操作するアカウント	あなた（あなたの Google アカウント）	ボットの ID
アクセスできる範囲	あなたが閲覧できるすべてのシート	ボットのメールアドレスと明示的に共有されたシートのみ
ブラウザーが必要か	はい（初回呼び出し時に一度だけ）	不要
トークンの更新	自動	該当なし

選択は自動で行われます。環境変数 GOOGLE_APPLICATION_CREDENTIALS が設定されている場合、サーバーはサービスアカウントモードを使用し、それ以外の場合はOAuthモードを使用します。

OAuth の設定

1. https://console.cloud.google.com/ にアクセスし、プロジェクトを作成するか選択します。

2. API とサービス → ライブラリ：Google Sheets API と Google Drive API を有効にします。

3. API とサービス → OAuth 同意画面：「外部」アプリ（Workspace をご利用の場合は「内部」）を設定します。テストユーザーとして自分を追加します。

4. API とサービス → 認証情報 → 認証情報を作成 → OAuth クライアント ID：

   • アプリケーションの種類：デスクトップアプリ。
   • 名前：任意です。

5. JSON をダウンロードします。

6. 次の場所に保存します。

   • Windows：%USERPROFILE%\.mcp-google-sheets\gdrive-credentials.json
   • macOS / Linux：~/.mcp-google-sheets/gdrive-credentials.json

   （環境変数 GSHEETS_CONFIG_DIR でディレクトリを変更できます。）

いずれかのツールを初めて実行すると、サーバーがブラウザーを開き、アクセスを許可するよう求めます。生成されたトークンは、認証情報と同じ場所にある gdrive-token.json に保存されます。次回以降の実行では、トークンが自動的に更新されます。更新に失敗した場合（トークンが取り消された場合など）は、gdrive-token.json を削除してください。次回の呼び出しで、ブラウザーを使った認証フローが再び実行されます。

サービスアカウントの設定（オプトイン、ヘッドレス）

1. Google Cloud Console で、プロジェクトの Google Sheets API と Google Drive API を有効にします（OAuth の場合と同じです）。
2. IAM と管理 → サービスアカウント → サービスアカウントを作成を選択します。名前を付けます。この用途では、プロジェクトレベルのロールは必要ありません。
3. サービスアカウントを開き、鍵 → 鍵を追加 → JSON を選択します。ファイルをダウンロードします。
4. ファイルを読み取り可能な任意の場所（例：~/.mcp-google-sheets/sa-key.json または CI のシークレットパス）に配置します。
5. サーバーの起動時に環境変数を設定します。
   • シェル：export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/sa-key.json
   • Claude の設定：サーバーのエントリーに追加します（下記参照）。
6. サーバーからアクセスするすべてのスプレッドシートを、サービスアカウントのメールアドレスと共有してください（鍵 JSON の client_email に記載されています。[email protected] のような形式です）。これを行わない場合、認証情報が有効でも呼び出しは 403 エラーになります。

このモードではトークンファイルはありません。サーバーは必要に応じて新しいアクセストークンを取得します。ブラウザーを使った認証フローはありません。

サーバーを登録する

グローバルインストール後、mcp-google-sheets-full バイナリが PATH 上で利用可能になります。

Claude Code（プロジェクトまたはユーザースコープ）

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

Claude Desktop（claude_desktop_config.json）

OAuth モード（デフォルト）：

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

サービスアカウントモード — サーバーをヘッドレス認証に切り替えるには、環境変数を追加します。

{
  "mcpServers": {
    "google-sheets": {
      "command": "mcp-google-sheets-full",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/sa-key.json"
      }
    }
  }
}

Claude Desktop がコマンドを見つけられない場合（macOS／Windows では PATH が無視されることがあります）、npm bin -g で確認できる絶対パスの末尾に /mcp-google-sheets-full（Windows の場合は .cmd）を付けて指定してください。

認識される環境変数：

• GOOGLE_APPLICATION_CREDENTIALS — サービスアカウントの JSON 鍵ファイルのパスを設定すると、サーバーはサービスアカウントモードに切り替わります。未設定の場合は OAuth モードになります。
• GSHEETS_CONFIG_DIR — OAuth の認証情報／トークンを保存するディレクトリを変更します（デフォルト：~/.mcp-google-sheets）。

run_sheets_script の使用

呼び出し元が便利なツールでは対応できない処理（複数ステップの操作、カスタムの batchUpdate 構成、Drive 操作、アドホック分析など）を行う必要がある場合、Node.js コードを渡します。ハーネスが認証済みコンテキストを事前に作成するため、スクリプト本体では sheets、drive、spreadsheetId をそのまま使用できます。構造化された値を返すには、result に代入します。

コード本文の例：

// List all tabs and their first row
const meta = await sheets.spreadsheets.get({ spreadsheetId });
const headers = {};
for (const s of meta.data.sheets) {
  const r = await sheets.spreadsheets.values.get({
    spreadsheetId,
    range: `${s.properties.title}!1:1`,
  });
  headers[s.properties.title] = r.data.values?.[0] ?? [];
}
result = headers;

ハーネスはコードを非同期 IIFE でラップするため、トップレベルの await をそのまま使用できます。エラーはスタックトレースとゼロ以外の終了コードとともに報告されます。一時ファイルは、どの実行経路でも削除されます。

提供されるツール

ツール	用途
auth_status	サーバーが認証情報／トークンを探す場所と、それらが存在するかどうかを確認します。
resolve_url	Google Sheets の URL から spreadsheetId と gid を抽出します。
list_spreadsheets	ユーザーの Drive 内のスプレッドシートを一覧表示します（最近使用したものが先）。
search_spreadsheets	名前の一部または全文検索でスプレッドシートを検索します。
get_spreadsheet	スプレッドシートのメタデータ（タブ、gridProperties）を取得します。
get_values	1 つの A1 範囲を読み取ります。
batch_get_values	複数の範囲を読み取ります。
update_values	2 次元配列を範囲に書き込みます。
batch_update_values	1 回の呼び出しで複数の範囲に書き込みます。
append_values	テーブルの末尾に行を追加します。
clear_values	1 つ以上の範囲をクリアします。
batch_update	構造を変更します（Sheets API の Request[] をそのまま使用）。専用ツールで対応していないあらゆる Request タイプに対応するための代替手段です。
create_spreadsheet	ユーザーが所有する新しいスプレッドシートを作成します。
add_sheet / delete_sheet / duplicate_sheet / rename_sheet	タブを管理します（sheet_id の gid または sheet_name を指定）。
insert_rows / insert_columns / delete_rows / delete_columns	0 始まりのインデックス範囲で行／列を管理します。
merge_cells / unmerge_cells	範囲を結合します（MERGE_ALL / MERGE_COLUMNS / MERGE_ROWS）。
format_cells	範囲に部分的な CellFormat を適用します（背景、textFormat、配置、numberFormat など）。
set_borders	範囲の枠線を設定します（top/bottom/left/right/innerHorizontal/innerVertical）。
run_sheets_script	認証済みの sheets/drive/auth/spreadsheetId を使って任意の Node コードを実行します。

注意事項

• 初回の認証中、OAuth フローは http://localhost:3456 でリクエストを待ち受けます。このポートが空いていることを確認してください。
• 要求されるスコープ：https://www.googleapis.com/auth/spreadsheets と https://www.googleapis.com/auth/drive。
• run_sheets_script は呼び出しごとに新しい node プロセスを実行します。同じ ~/.mcp-google-sheets/ の認証情報とトークンを再利用します。タイムアウトは設定可能です（デフォルトは 2 分、最大 10 分）。