google-drive-files-mcp

google-drive-files-mcp

Google Drive のファイル管理（移動、アップロード、整理）、Google Sheets の編集（セル、行、タブ、書式）、Google Docs の精密な編集（フレーズの置換、アンカー位置への挿入、範囲の削除。他のすべての書式は保持）に特化した Model Context Protocol サーバー（およびスタンドアロン CLI）です。粒度の細かい単一目的のツールを23個備えており、それぞれが明示的な操作を行います。書き込み操作では変更前後の状態または正確なインデックスを返すため、何も気づかないうちに変更されることはありません。

ホスト型の Google Drive コネクターではファイルの検索、読み取り、コピーはできますが、移動はできません（copy はファイルを移動するのではなく、新しい ID で複製します）。また、実際のバイナリファイルを確実にアップロードすることもできません（インラインコンテンツ API ではバイト列を base64 として埋め込む必要があるため、大容量ファイルやバイナリファイルではうまく動作しません）。さらに、スプレッドシートやドキュメントの内容をその場で編集することもできません。このサーバーは、真の移動機能、ローカルパスからのレジューム可能なアップロード、フォルダー作成、Google Sheets の編集機能一式、範囲を指定した Google Docs の編集機能を追加します。あらゆる MCP クライアント（Claude Code、Claude Desktop、Cursor、Cline など）で使用できます。

ツール

Drive — ファイルとフォルダー

• drive_search(query, only_folders=False, max_results=20) — ファイルやフォルダー（およびその ID）を検索します。
• drive_create_folder(name, parent=None) — フォルダーを作成します（parent には ID、URL、root、または一意に特定できるフォルダー名を指定できます）。
• drive_move(file, dest_folder, keep_existing_parents=False) — 真の移動（現在のフォルダーから削除されます）。keep_existing_parents=True を指定すると、削除せずに追加します。
• drive_upload_file(local_path, parent=None, name=None, mime_type=None) — レジューム可能なメディアアップロードを使用して、ローカルファイル（大容量バイナリを含むあらゆる種類）をアップロードします。そのまま保存されます（Google 形式への変換は行いません）。

Google Sheets — 読み取り、編集、構造、書式設定

• sheets_get_info(spreadsheet) — タブとサイズの一覧を取得します（タブ名を確認するため、最初に呼び出してください）。
• sheets_read(spreadsheet, range_a1, render_option="FORMATTED_VALUE") — 範囲を読み取ります（FORMULA／UNFORMATTED_VALUE も使用できます）。
• sheets_write(spreadsheet, range_a1, values, value_input_option="USER_ENTERED") — 範囲を上書きし、before を返します。USER_ENTERED は数値を解析し、=SUM(..) を数式として扱います。RAW は文字どおりに書き込みます。
• sheets_append(spreadsheet, range_a1, values, ...) — 表の後に行を追加します。
• sheets_clear(spreadsheet, range_a1) — 書式を保持したまま値を消去し、before を返します。
• sheets_batch_write(spreadsheet, updates, ...) — 複数の範囲に対して一括で書き込みます。
• sheets_add_tab／sheets_rename_tab／sheets_delete_tab — タブを管理します（削除は取り消せません）。
• sheets_freeze_panes(spreadsheet, tab, rows=None, cols=None) — ヘッダー行／列を固定または固定解除します（0 = 明示的に固定解除、指定を省略 = 変更なし）。
• sheets_format(spreadsheet, range_a1, number_format=None, bold=None, background=None, wrap=None) — 数値形式のパターン／太字／#RRGGBB の背景色／テキストの折り返しを設定します。
• sheets_set_column_width(spreadsheet, range_a1, pixel_size) — 列全体の範囲（例：'A:C'）に対して、列幅をピクセル単位で設定します。
• sheets_set_row_height(spreadsheet, range_a1, pixel_size) — 行全体の範囲（例：'2:5'）に対して、行の高さをピクセル単位で設定します。

Google Docs — その場での精密な編集

Docs の編集はすべて範囲を指定して実行されるため（documents.batchUpdate）、対象だけを正確に変更し、それ以外のすべてのランのネイティブ書式はバイト単位でそのまま保たれます。

• docs_get_info(document) — タイトルと構造（段落数／テーブル数、終了インデックス）。
• docs_read(document) — セグメントごとの文字インデックス付きの全文（テーブルのセルには行／列が含まれます）。編集対象を指定するため、最初にこれを読み取ってください。
• docs_replace_text(document, find, replace, match_case=False) — フレーズをすべて置換します。周囲のコンテンツや書式は変更されません。
• docs_insert_text(document, text, index=None, after_text=None, before_text=None) — インデックス位置、またはアンカーフレーズの直後／直前に挿入します。
• docs_delete_range(document, start_index, end_index) — 指定した範囲だけを削除します。
• docs_append_text(document, text) — 文書の末尾に追加します。

ファイルの名前変更／コピー／ゴミ箱への移動／削除には対応していません（コピー機能はホスト型の Drive コネクターにすでにあります）。破壊的な操作（sheets_clear、sheets_delete_tab、docs_delete_range）はそれぞれ独立した明示的なツールなので、実行タイミングを正確に制御できます。

スコープに関する警告（お読みください）

既存の任意のファイルを移動するには、完全な drive スコープが必要です。これは Drive 内のすべてのファイルに対する読み取り／書き込み／削除権限を意味します。ファイルの親を変更できる、これより限定的なスコープはありません（drive.file の対象はアプリ自身が作成したファイルのみです）。したがって、このツールは読み取り専用コネクターよりもはるかに強力です。キャッシュされたトークンはパスワードと同様に扱い（0600 で保存）、読み取り専用ツールとの共有は避けて、分離した OAuth クライアント／トークンを使用してください。

インストール

pip install google-drive-files-mcp
# or: uv tool install google-drive-files-mcp

初回セットアップ（約10分）

1. Google Cloud Console → プロジェクトを作成／選択します。
2. Drive API（リンク）を有効にします。Sheets ツールを使う場合は Sheets API（リンク）も、Docs ツールを使う場合は Docs API（リンク）も有効にします。（完全な drive スコープでは Sheets API と Docs API もすでに許可されています。追加の同意は不要で、使用する API をそれぞれ有効にするだけです。）
3. OAuth 同意画面 → Internal（Workspace。制限付きの完全な Drive スコープでも検証は不要）または External ＋ 自分をテストユーザーとして追加（個人用 Gmail）。
4. 認証情報 → OAuth client ID → Desktop app → JSON をダウンロードします。
5. google-drive-files-mcp setup --import-credentials ~/Downloads/client_secret_*.json → ブラウザーで同意します。

確認：

google-drive-files-mcp status
google-drive-files-mcp search "Reports" --folders

Claude Code

claude mcp add --scope user google-drive-files google-drive-files-mcp -- serve

「Q2 Report」というドキュメントを探して、「2026 Reports」フォルダーに移動してください。

Claude Desktop

{
  "mcpServers": {
    "google-drive-files": { "command": "google-drive-files-mcp", "args": ["serve"] }
  }
}

CLI

google-drive-files-mcp search "budget"                 # find a file + its ID
google-drive-files-mcp search "Reports" --folders      # find destination folders
google-drive-files-mcp mkdir "2026 Reports"            # create a folder
google-drive-files-mcp move <file-url-or-id> "2026 Reports"   # move into it (by folder name)
google-drive-files-mcp move <file-url-or-id> root      # move back to My Drive root
google-drive-files-mcp upload ~/Downloads/report.zip --parent "2026 Reports"   # upload a local file

# Google Sheets
google-drive-files-mcp sheet-info  <sheet-url-or-id>                 # list tabs + sizes
google-drive-files-mcp sheet-read  <sheet-url-or-id> "Sheet1!A1:D10" # read a range
google-drive-files-mcp sheet-write <sheet-url-or-id> "Sheet1!B2:B4" '[[100],[200],[300]]'   # set numbers
google-drive-files-mcp sheet-format <sheet-url-or-id> "Sheet1!B2:B4" --number-format '#,##0.00' --bold
google-drive-files-mcp sheet-format <sheet-url-or-id> "Sheet1!A1:B2" --wrap             # wrap text
google-drive-files-mcp sheet-freeze-panes <sheet-url-or-id> Sheet1 --rows 1             # freeze header row
google-drive-files-mcp sheet-set-column-width <sheet-url-or-id> "Sheet1!A:C" 150        # column width (px)
google-drive-files-mcp sheet-set-row-height <sheet-url-or-id> "Sheet1!2:5" 40           # row height (px)

# Google Docs (surgical, in-place)
google-drive-files-mcp doc-read    <doc-url-or-id>                       # text + character indices
google-drive-files-mcp doc-replace <doc-url-or-id> "old phrase" "new phrase"   # preserves all other formatting
google-drive-files-mcp doc-insert  <doc-url-or-id> $'\n\nNew paragraph.' --after "some anchor text"

drive_move は移動前後の親を返すため、移動を監査できます：

{ "id": "1Abc…", "name": "Q2 Report", "moved_from": ["0OldFolderId"], "moved_to": "1NewFolderId", "parents_now": ["1NewFolderId"], "web_view_link": "https://docs.google.com/…" }

設定

変数	デフォルト	内容
GDRIVE_FILES_MCP_CREDENTIALS	~/.config/google-drive-files-mcp/credentials.json	OAuth クライアントシークレット
GDRIVE_FILES_MCP_TOKEN	~/.config/google-drive-files-mcp/token.json	キャッシュされた更新トークン
GDRIVE_FILES_MCP_SCOPES	https://www.googleapis.com/auth/drive	OAuth スコープ（カンマ区切り）

安全に関する注意

• ファイルを実際に移動すると、現在のフォルダーからそのファイルが取り除かれます。 Drive のアイテムは複数の親を持てます。keep_existing_parents=True を指定すると、既存の親を取り除かずに追加します。
• 移動先のフォルダー名は一意である必要があります。 同じ名前のフォルダーが2つある場合、drive_move は移動を拒否し、候補の一覧を表示するため、明示的な ID を渡せます。
• 移動のたびに移動前後の親が返されます。エージェント（またはユーザー）が結果を確認できます。

トラブルシューティング

HttpError 403: Google Drive API has not been used in project … or it is disabled OAuth クライアントを所有するプロジェクトで Drive API を有効にしてください：console.cloud.google.com/apis/library/drive.googleapis.com → 有効にするを選択し、約 1 分待ってから再試行してください。（初回実行時に最もよく発生するエラーです。）

multiple folders named '…'; pass the folder ID/URL instead 同じ名前のフォルダーが複数あるため、名前だけでは特定できません。google-drive-files-mcp search "<name>" --folders を実行して ID を取得し、正確な ID を指定してください。

no folder named '…' found まずフォルダーを作成する（google-drive-files-mcp mkdir "<name>"）か、フォルダー ID／URL／root を指定してください。

移動時に HttpError 403: insufficientFilePermissions が発生する トークンに完全な drive スコープがないか、ファイルまたは移動先の編集権限がありません。前者の場合は google-drive-files-mcp setup --reauth で再認証してください。後者の場合、所有者から編集権限を付与されていないファイルは移動できません。

Claude Desktop／cron で No valid Google token が表示される 初回の同意にはブラウザーが必要です。ターミナルで google-drive-files-mcp setup を一度実行してください。その後のヘッドレス実行では、キャッシュされたトークンが再利用され、自動更新されます。

移動によって共有フォルダーからファイルが意図せず「削除」された 実際に移動すると、アイテムは現在の親フォルダーから削除されます。元の場所にも残しておくつもりだった場合は、keep_existing_parents=true（CLI では --keep）を使用してください。

他のクライアントから使用する（Cursor、Cline、Continue など）

stdio に対応する MCP クライアントなら使用できます。詳しくは docs/other-clients.md をご覧ください。

認証 — Google OAuth クライアントをご自身で用意してください

API キーや同梱されたシークレットはありません。サーバーは、ご自身で作成した OAuth クライアントを使ってご自身の Google アカウントに認証し、更新トークンをローカルにキャッシュします。作者がデータにアクセスすることは一切ありません。

• 独自のクライアントが必要な理由： Google の制限付きスコープ（ここでは完全な drive スコープ）は共有アプリで再配布できず、未検証の共有アプリはユーザー数が 100 人に制限されます。「OAuth クライアントを自分で用意する」方式は、個人データを扱う MCP サーバーで標準的なパターンです。
• 必要なもの： 無料の Google Cloud プロジェクト、Drive API、有効化済みの OAuth 同意画面、デスクトップ OAuth クライアント。詳しい手順は docs/setup-google-oauth.md をご覧ください。
• トークンの保存場所： ~/.config/google-drive-files-mcp/token.json（モード 0600）。ローカルで無効にするには削除してください。完全に無効にするには myaccount.google.com/permissions から取り消してください。
• ホスト型／SaaS の選択肢はありません — すべてローカルで実行され、Drive のデータがサードパーティのサーバーに渡ることはありません。

その他のガイド

• docs/setup-google-oauth.md — OAuth の詳しい手順（完全な drive スコープ）とよくあるエラー
• docs/claude-code.md · docs/claude-desktop.md · docs/other-clients.md
• examples/ — 例：文書を YYYY-MM フォルダーに整理する

関連ツール

ホスト型コネクターでは公開されていない Google Workspace データに特化した、小規模なローカル MCP サーバー群の一部です。

• gmail-attachments-mcp — Gmail の添付ファイルのデータをディスクにダウンロード
• google-drive-comments-mcp — Docs／Sheets／Slides のコメントスレッドを読み取り
• google-drive-files-mcp — Drive ファイルを移動／整理 (このリポジトリ)

同じ OAuth ログインを共有することも、個別に管理することもできます。各リポジトリのセットアップ方法をご覧ください。

ライセンス

MIT。詳しくは LICENSE をご覧ください。