title: "Google Drive MCP Server" date: 2026-08-19 tags:

• プロジェクト/workspace

• サブプロジェクト/tools

• タイプ/guide

• 領域/tech

• 日付/2026-08-19

Google Drive MCP Server

Cursor、Claude Code、Claude Desktop 用のローカル MCP サーバーです。このサーバーを通じて、エージェントは Google Drive 上のファイルを検索・読み取り、Google Docs や Google Sheets の作成・編集を行います。

Google Docs は読み取り時に Markdown に変換され、スプレッドシートは CSV、プレゼンテーションはテキストになります。Docs はポイント単位で編集可能です: 挿入、置換、スタイル、見出し、リスト、名前変更、複製。Sheets は値、書式、タブ、行と列を操作できます。個人用 Drive と Shared drives の両方で動作します。

リポジトリ: https://github.com/Stillfrozen/gdrive-mcp
wagnerlabs/gdrive-mcp をベースにしています。

OAuth キーはお使いのディスク上にのみ保存されます。git には含まれません。

Google Cloud でのステップバイステップのセットアップ (プロジェクト、API、Desktop OAuth、test users): docs/INSTALL.ru.md

クイックスタート

Node.js 18+ (できれば 20) と、作業対象の Drive を持つ Google アカウントが必要です。

git clone https://github.com/Stillfrozen/gdrive-mcp.git
cd gdrive-mcp
./scripts/install.sh

スクリプトが依存関係をインストールし、プロジェクトをビルドし、Google Cloud の設定を案内します: プロジェクト、API、同意画面、Desktop クライアント、ブラウザでのログイン。最後に MCP クライアント用の完成した設定断片を出力します。

変更せずに手順を確認する場合:

./scripts/install.sh --dry-run

自分で Console を操作したい場合は、docs/INSTALL.ru.md に画面の詳細な解説があります。

Cursor

~/.cursor/mcp.json (またはプロジェクト内の .cursor/mcp.json) に、絶対パス のみを指定します:

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"],
      "env": {
        "GDRIVE_OAUTH_PATH": "/absolute/path/to/gdrive-mcp/credentials/gcp-oauth.keys.json",
        "GDRIVE_CREDENTIALS_PATH": "/absolute/path/to/gdrive-mcp/credentials/.gdrive-server-credentials.json"
      }
    }
  }
}

env ブロックは、JSON がリポジトリの credentials/ にある場合は必須ではありません。ファイルに他のサーバーが既にある場合は、mcpServers 内に "gdrive" を追加してください。他の設定を上書きしないようにしてください。

次に Cursor → Settings → MCP → Reload を実行します。gdrive インジケーターが緑色になれば成功です。

Claude Code CLI

claude mcp add --scope user gdrive -- node /absolute/path/to/gdrive-mcp/dist/index.js

--scope user はサーバーをグローバルに設定します。解除するには: claude mcp remove gdrive。

Claude Desktop

claude_desktop_config.json 内:

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"]
    }
  }
}

Related MCP server: Google Drive MCP Server

ツール

読み取り

書き込み: Sheets

書き込み: Docs

セルへの値の書き込み方法

gdrive_update_sheet と gdrive_append_sheet の value_input_option パラメータ:

• USER_ENTERED (デフォルト) — Sheets の UI での入力と同じ。=SUM(A1:A10) のような数式は実行され、数値と日付は書式設定されます。

• RAW — そのまま。=SUM(A1:A10) という文字列はテキストのまま残ります。

ファイルの読み取り方法

gdrive_read_file は Workspace ドキュメントを自動的にエクスポートします:

スプレッドシート全体 (タブ、構造、書き込み) は、gdrive_read_file ではなく、gdrive_get_spreadsheet_info と Sheets の write ツールを使用してください。

Doc の段落、見出し、リスト、アンカー編集には gdrive_get_document_info を使用します。レスポンスには生の text と、段落の末尾の改行を含まない displayText があります。displayText の方がアンカーとして安全なことが多いです。Markdown は gdrive_read_file が最も速く取得できます。

セキュリティモデル

複数のレイヤーがあります: MCP アノテーション、「まず読み取り」、Docs にはさらにリビジョンとアンカー、Sheets には現在値の照合。

1. ツールのアノテーション

各ツールは MCP annotations を宣言します。クライアントは破壊的操作の前に確認を求めることができます。上記の表の Destructive / Idempotent 列を参照してください。

2. まず読み取り、それから書き込み

サーバーは、エージェントがこのセッションで既に開いたスプレッドシートと Docs を記憶しています。

スプレッドシートは以下を実行した後に読み取られたと見なされます:

• gdrive_read_file (セルを CSV として)

• gdrive_get_spreadsheet_info (構造とタブ)

• gdrive_create_sheet (エージェントが自分で作成したばかりのファイル)

Doc は以下を実行した後に読み取られたと見なされます:

• gdrive_read_file (Markdown + Google が提供する場合はリビジョン)

• gdrive_get_document_info (タブまたは構造化テキスト)

• gdrive_create_doc

このステップなしの書き込みは拒否されます:

You must read this spreadsheet before writing to it…

You must read this document before writing to it…

これにより、エージェントが誤ったファイルを対象にする可能性が低くなります。リストはプロセス再起動時にリセットされます (各 MCP セッションは新規)。

gdrive_get_file はこれに含まれません: これは Drive のメタデータのみで、コンテンツではありません。

3. リビジョンを考慮した Docs への書き込み

編集は、エージェントが最後に読み取ったリビジョンに紐付けられます:

• conflict_mode: "strict" (デフォルト) — Docs の requiredRevisionId。ドキュメントが変更された場合、書き込みは失敗します。

• conflict_mode: "merge" — Docs の targetRevisionId。Google は可能な限り他の編集とマージします。

構造化コンテンツのキャッシュは、gdrive_get_document_info include_content=true の後、セッション内に保持されます。アンカーツール (gdrive_insert_doc_text、gdrive_replace_doc_text、gdrive_update_doc_paragraph_style、gdrive_update_doc_list) は、リビジョンが同じである限り、このキャッシュを使用します。それ以外の場合は、サーバーがスナップショットを再取得します。

テキストのポイント単位の置換には、expected_text を渡すことができます: 送信前にサーバーが範囲内の文字列が正確に一致するか照合します。

アンカー型の gdrive_delete_doc_text と gdrive_replace_doc_text では、一致がタブの末尾に接する場合、サーバーは段落の末尾の改行のみを自動的に切り取ります。Docs API は、セグメントの終端の newline を含む範囲を削除できません。明示的な start_index / end_index ではこれは行われません: 末尾の newline は自分で除外する必要があります。

4. Sheets の前提条件

gdrive_update_sheet にはオプションの expected_current_values があります。これは values と同じ形状の 2 次元配列です。サーバーはセルを読み取り、比較します。一致しない場合、書き込みは拒否され、エラーには実際のコンテンツが含まれます。

• ポイント単位の編集 (1 セル、数式) — expected_current_values を渡してください。

• 一括操作 (数千行) — 渡さないでください。リクエストが 2 倍になり、クォータに達します。

include_previous_values: true は監査用に古い値を返します。expected_current_values が指定されている場合、古い値は常に返されます。

ロールバック

Docs と Sheets の編集は Google Workspace のバージョン履歴に表示されます。そこでロールバックできます。

どのツールも Drive からファイル全体を削除しません。 破壊的操作は Doc 内とスプレッドシート内のみです。ファイルの削除は Drive の UI からのみ可能です。

設定

キーへのパスは環境変数で上書きできます:

アップデート

git pull の後、upgrade を実行してください。プロジェクトを再ビルドし、setup-manifest.json に新しい API や scope が追加された場合は、auth を再実行するよう求めます:

cd /path/to/gdrive-mcp
git pull
./scripts/upgrade.sh

マニフェストが変更されていない場合、スクリプトは再ビルドのみ行い、最新であることを通知します。Cursor は MCP の Reload 後に dist/ を取得します。サーバーの再登録は不要です。

scope について: サーバーは狭い drive.file ではなく、完全な drive を要求します。これは Google の最小推奨よりも広いですが、そうしないと任意の利用可能なファイルを読み取ったり、既存の Docs に書き込んだり (rename、duplicate、編集) できません。構造化読み取りと batchUpdate には documents scope が必要です。

Testing ステータスの External アプリケーションでは、refresh token の有効期限は 7 日間です。その後は invalid_grant となり、再度 npm run auth を実行します。詳細とオプション (Internal / Publish) は docs/INSTALL.ru.md にあります。

制限事項

• gdrive_create_sheet はスプレッドシートを Drive のルートに配置します。フォルダを選択することはできません。

• Sheets の gdrive_read_file は最初のタブのみを CSV で返します。他のタブは gdrive_get_spreadsheet_info を使用します。

• Docs の gdrive_read_file は常に Markdown です。タブ、段落の境界、リスト、アンカーは gdrive_get_document_info を使用します。

• Doc の書式と構造を変更する前に、まず gdrive_get_document_info include_content=true を読んでください。

• gdrive_replace_all_doc_text はデフォルトで最初のタブのみを対象にします。すべてのタブを対象にするには、明示的に all_tabs: true を指定する必要があります。

開発

npm install
npm run dev          # tsx, без сборки
npm run build
npm test
npm run test:live    # живой Google Doc, нужны сохранённые credentials
npm run test:watch

npm run test:live は一時的な Doc を作成し、MCP と同じストリームを介してテキストを挿入し、gdrive_get_document_info で確認して、最後にファイルをゴミ箱に入れます。

ライセンス

MIT