drivelift

v0.5.1

Published

3 days ago

Lift local files into Google Drive as native Docs/Sheets/Slides — a bring-your-own-OAuth-client MCP server and CLI for LLM agents (Google Drive only, drive.file scope, guided setup).

0High
0Medium
0Low

rererr

mcp model-context-protocol google-drive google-sheets google-docs upload llm claude-code

drivelift

ローカルのファイルを Google Drive へ持ち上げ、Google スプレッドシート／ドキュメント／スライドとして置く MCP サーバー兼 CLI。LLM エージェント（Claude Code、Cursor、Codex など）が作った xlsx や md を、書式を保ったまま Drive の URL にする。

English

何を解くか

エージェントが手元に書いた成果物を Drive に載せたい場面で、既存の Drive コネクタはローカルファイルを受け取れない。中身を base64 にして会話に通すと、数十 KB のバイナリでも壊れる。

drivelift は利用者のマシンで動き、ツールにファイルパスを渡すだけで済む。バイト列は会話を通らず、Drive API へ直接流れる。xlsx から Google スプレッドシートへの変換は Drive 自身のインポート機能で行うので、列幅・塗り・タブ・埋め込み画像のような書式はその機能が保つ範囲でそのまま残る（rclone の --drive-import-formats と同じ経路）。

設計上の約束

共有の OAuth クライアントを持たない。 利用者が自分の Google Cloud プロジェクトでクライアントを作る（5 分程度）。未設定のときはツールが Console の URL を順に返して誘導する
スコープは drive.file だけ。 drivelift が作ったファイル以外は見えない。既存の共有資料を壊す経路がない
secret を会話に通さない。 クライアント JSON の取り込みはファイルパス指定のみ
ホスティング不要。 ループバック（127.0.0.1）でログインし、トークンは手元に置く
依存は MCP SDK と zod の 2 つ。Drive API は標準の fetch で叩く

導入

Claude Code の場合、プロジェクトの .mcp.json に追加する。

{
  "mcpServers": {
    "drivelift": {
      "command": "npx",
      "args": ["-y", "drivelift@0"]
    }
  }
}

または claude mcp add drivelift -- npx -y drivelift@0。CLI として使うなら npx drivelift doctor。

Node.js 22.13 以降が必要。

初回セットアップ

エージェントに「drivelift の status を見て」と言えば、以下を返してくる。手順を自分で踏む場合は同じ内容。

Google Cloud プロジェクトを作る（既存でも可）: https://console.cloud.google.com/projectcreate 。gcloud が入っていれば gcloud_setup ツールが手順 1・2 を代理実行する。ツールは打つコマンドを先に見せ、承認を得てから実行する。CLI では drivelift setup-gcloud で計画を表示し、--yes を付けると実行する。手順 3・4 に gcloud の代替はない
Google Drive API を有効化: https://console.cloud.google.com/apis/library/drive.googleapis.com
OAuth 同意画面を設定: https://console.cloud.google.com/auth/overview
- Google Workspace のアカウントなら内部（審査不要。テスト状態の7日失効も起きない）
- 個人 Gmail なら外部にして 本番に公開する。テスト状態のままだとリフレッシュトークンが 7 日で失効する
OAuth クライアントを デスクトップアプリ 種別で作り、JSON をダウンロード: https://console.cloud.google.com/auth/clients/create
JSON を import_client_secret ツール（CLI: drivelift import-secret <path>）で取り込む。中身を検証して設定ディレクトリへ 0600 で保存する。パスを省くと ~/Downloads の候補を新しい順に列挙するだけで、コピーはしない（status / doctor も候補を candidates に出す）。取り込みはコピーなので、~/Downloads の元ファイルは残る。不要なら自分で消す
auth_start ツール（CLI: drivelift login）でブラウザが開くのでログインする。ツールは同意が終わるまで待つので、終わったことを伝え直す必要はない。複数の Google アカウントを使うときは「複数の Google アカウント」を参照

以後は upload を呼ぶだけ。設定が欠けた状態で upload を呼んでも、同じ手順が next_steps として返る。

ツール

| ツール | 役割 | |--|--| | status | 導入状態（no_client / no_token / token_invalid / api_disabled / ready、複数アカウントで使う枠が決まらなければ account_unresolved）と次の一手、Console の URL。ログイン済みのアカウントごとの状態（accounts）と、作業ディレクトリから解決される枠（resolved）も返す | | auth_start | ログイン開始。ブラウザを開き、同意が終わるまで最大 wait_seconds（既定 45 秒）待って completed を返す。間に合わなければ pending。login_hint にメールアドレスを渡すと、ログインするアカウントとして Google に伝える | | auth_status | ログインの進捗（idle / pending / completed / failed）。wait_seconds で決着まで待てる | | import_client_secret | ダウンロード済みのクライアント JSON を設定ディレクトリへ取り込む | | gcloud_setup | gcloud が入っていれば手順 1・2（プロジェクト用意と Drive API 有効化）を代理実行。confirm なしは打つコマンドを返すだけで、confirm: true で実行。gcloud 未ログインなら gcloud auth login も代行（ブラウザが開く） | | upload | ファイルを Drive へ置き、URL を返す | | map_source | 到達元（リポジトリの git remote、または git でないディレクトリの絶対パス）をアカウントに対応づける。remove: true で外す。source を省くと、path（省略時は作業ディレクトリ）の到達元を返すだけで何も書かない |

upload の引数:

replace_id は同じレポートを直して配り直すためのもの。差し替えは中身の全置き換えで、Sheets 上で直接加えた編集やコメントは消える（以前の版は Drive の版の履歴に残る）。シートの内部 ID も変わるので、特定のタブを指すリンク（#gid=）は切れる。取り違えを防ぐため、差し替え先がゴミ箱にあるとき、今回のアップロード名と名前が違うとき、種類が違うとき（スプレッドシートにドキュメントを上げる等）は、送信せずに拒否する。drive.file の範囲なので、drivelift が作っていないファイルは差し替えられない。

共有は、利用者が指示したときだけ付ける前提で、ツールの説明にもそう書いてある。anyone は「リンクを知っている全員」になり外部公開と同じなので、利用者が明示したときだけ使う。共有の一部が失敗してもアップロードは取り消さず、結果の shared に1件ずつ成否を返す。

share_new_folder は、PR ごと・日付ごとのフォルダをチームに URL で渡すためのもの。フォルダへの共有の成否は folder_shared に返る（付けなかったときは空）。共有するのは末端のフォルダ（結果の folder_id）だけで、途中の階層を新しく作っていてもそこには付けない。フォルダの共有は中身に継承されるので、そのフォルダに後から置いたファイルも同じ相手に見える。再利用したフォルダに付けないのは、以前置いたファイルまで見えるようになるのを防ぐため。そのため、この機能より前に作ったフォルダや、作成時に共有が失敗したフォルダは、次回以降も共有されない。必要なら Drive の画面で手動で共有する。

auto の変換先: xlsx・xlsm・xls・ods・csv・tsv → スプレッドシート、docx・doc・odt・rtf・txt・md・html・htm → ドキュメント、pptx・ppt・odp → スライド。それ以外はそのまま置く。変換は Drive のインポート機能が行う。実機で確認したのは xlsx・csv（スプレッドシート）と md（見出しや表を解釈したドキュメント）で、ほかは Drive の対応形式に従う。

CLI

drivelift                       MCP stdio サーバーとして起動
drivelift doctor                導入状態と次の一手、ログイン済みのアカウントと解決される枠
drivelift login [--hint EMAIL]  ブラウザでログイン（完了まで待つ）
drivelift import-secret [path]  クライアント JSON の取り込み
drivelift setup-gcloud [--project ID] [--yes]  gcloud で手順 1・2 を実行（--yes なしは計画表示）
drivelift upload <file> [--account EMAIL] [--folder ID] [--folder-path A/B] [--name N] [--convert MODE]
                 [--share ROLE:TYPE[:TARGET]]... [--share-new-folder] [--notify] [--replace ID] [--json]
drivelift map <email> [source] [--remove]  到達元をアカウントに対応づける（source を省くと作業ディレクトリの到達元を表示するだけ）

upload は既定で URL だけを標準出力に出すので、スクリプトから拾いやすい。--share は繰り返し指定できる（例: --share reader:domain:example.com --share writer:user:[email protected]）。共有に1件でも失敗すると（--share-new-folder によるフォルダの共有を含む）、URL は出したうえで終了コード 3 を返す。--share-new-folder を付けたのにフォルダが既存だった場合は、共有しなかったことを標準エラーに出す（終了コードは 0）。アカウントが決まらずに拒否したときは終了コード 2。--account で送ったとき、到達元の git リポジトリがどのアカウントにも対応づいていなければ、対応づける drivelift map のコマンドを標準エラーに出す（シェルの特殊文字を含む引数は単一引用符で囲む）。到達元が別のアカウントに対応づいていれば、そのことを標準エラーに出す（送信はする）。

設定

アカウントの枠は、ログインしたときに about.get で取れたメールアドレスの名前で作られる。メールアドレスが取れなければ（Drive API が有効になっていない等）、ログインは失敗し、何も保存しない。Drive API を有効にしてからログインし直す。

0.4.0 からの移行

0.4.0 までは ~/.config/drivelift/token.json の 1 枠だけだった。0.5.0 以降はこのファイルを読まず、最初に status・upload・map_source（CLI では doctor・upload・map）を呼んだときに、そのアカウントの枠へ写す。写す前に今のクライアントで 1 回 refresh し、通ることを確かめる。通らなければ写さず、理由（invalid_grant、invalid_client、通信の失敗）を返す。ログイン済みのアカウントが 1 つも無い状態では、3 つのツールのどれを呼んでもこの理由が返る。ファイルが壊れていれば、ログインし直すよう案内する。

写した結果は、token.json の内容のハッシュと一緒に legacy-migration.json に残す。内容が同じ間は写し直さない。Google が拒否した（invalid_grant、invalid_client）場合も、ファイルが変わるまで再試行せず、status に理由と消し方を出し続ける。通信の失敗は記録せず、次の呼び出しで再試行する。0.4.0 側でログインし直すなどで token.json が変われば写し直すが、同じアカウントの枠が既にあればその枠には触れない（0.5.0 でログインし直した枠を、古いトークンで戻さないため）。

トップレベルの client_secret.json を差し替えてもログイン済みのアカウントは消えない。各枠が自分のクライアントの写しで refresh を続ける。

元の token.json は消さない。動いている 0.4.0 のプロセスや、0.4.0 を使う別の設定は、元のファイルをそのまま使い続けられる。0.5.0 以降だけを使うなら rm ~/.config/drivelift/token.json で消してよく、status もそう案内する。

複数の Google アカウント

案件ごとに Google アカウントを分けている場合は、アカウントごとにログインし、作業リポジトリ（到達元）をアカウントに対応づける。1 つのアカウントに複数の到達元を対応づけられる。

drivelift login --hint [email protected]
drivelift login --hint [email protected]
cd ~/work/client-a-repo && drivelift map [email protected]

map は source を省くと、作業ディレクトリの到達元（例: github.com/client-a/repo）を表示するだけで何も書かない。表示を確かめてから drivelift map [email protected] github.com/client-a/repo で対応づける。ツールでは map_source が同じ働きをする。

到達元は、git の作業ツリーなら remote origin の URL を正規化したもの（https://・git@host:・port・.git・末尾の / の違いを吸収した github.com/org/repo）で表す。clone 先や worktree が変わっても同じ到達元になる。origin の無い git は git ルートの絶対パス、git でないディレクトリは絶対パスで表し、対応づけた絶対パスの配下にも当たる。

パスの対応づけは、origin のある git の作業ツリーの中には当たらない。 その中の到達元は remote になるため。リポジトリは remote で対応づける
パスの対応づけが重なるときは、長い方が勝つ（最長一致）。 /work を A、/work/clientB を B に対応づけると、/work/clientB/x は B、それ以外の /work の下は A になる
ルート（/）・ホームディレクトリ・一時ディレクトリ（/tmp・/var/tmp を含む）と、それらの親は対応づけられない。 前方一致でほぼ全ファイルが当たるため。ホームを丸ごと git で管理している（dotfiles）場合、その remote も同じ理由で suggest_map に出さず、map の候補でも対応づけられないと返す。remote を source に明示したときは、作業ディレクトリの git がその remote を指している場合に限り拒否する（それ以外は作業ツリーの広さを知りようがない）
git remote は host 付きで渡す（github.com/owner/repo、または clone の URL）。owner/repo だけでは受け付けない。ドットの無い host（社内の git サーバー等）は clone の URL（git@gitserver:org/repo・https://gitserver/org/repo）で渡す
remote は全体を小文字に揃える。パスは realpath で実際の綴りに揃える。 シンボリックリンクは実体になり、大文字小文字を区別しないファイルシステム（macOS の既定）ではディスク上の綴りになる。存在しないパスは対応づけられない（外すことはできる）
git が読めないときは、到達元が分からないものとして扱う。 git が入っていない場合や、所有者の違うリポジトリ（dubious ownership）の場合。パスの対応づけには落とさず、アカウントが 2 つ以上あれば拒否する。理由は status の resolved.reason と拒否の応答に入る

upload は次の順でアカウントを決める。

引数 account（CLI: --account）
環境変数 DRIVELIFT_ACCOUNT。プロジェクトの .mcp.json の env に置けば、そのプロジェクトからは常にそのアカウントを使う
アップロードするファイルの到達元を、各アカウントの sources.json で引く
ログイン済みのアカウントが 1 つならそれ
どれにも当たらずアカウントが 2 つ以上あれば、何も送らずに拒否する。応答に選べるアカウントの一覧（candidates）と到達元（source）が入るので、どのアカウントで送るかを利用者が決める

同じ到達元が 2 つのアカウントに対応づいている場合（sources.json を手で書いた等）も、5 と同じく拒否する。結果の account は使ったアカウント、source は解決に使った到達元（引数・環境変数・唯一のアカウントで決まったときは null）。

対応づけは自動では書かない。account を付けて上げたとき、到達元の git リポジトリがどのアカウントにも対応づいていなければ、結果に suggest_map（source と account）が入る。エージェントはこれを見て、利用者に対応づけを申し出る。map_source は利用者が承認したときだけ呼ぶ前提で、ツールの説明にもそう書いてある。

パスの到達元（git でないディレクトリ、origin の無い git）では suggest_map を出さない。パスの対応づけは配下のファイルすべてに効くので、エージェントの提案からではなく、利用者が map_source（map）で明示したときだけ作る。

account で指定したアカウントが、到達元に対応づいているアカウントと違っても、指定どおりに送る。そのとき結果に mapped_to（対応づいているアカウント）が入るので、エージェントは意図したアカウントかを利用者に確かめる。

別のアカウントに対応づいている到達元は、map_source で追加できない。付け替えるには、先に元のアカウントから remove: true で外し、それから追加する。2 回に分けてあるのは、注入された 1 回の呼び出しで送り先を恒久的に変えられないようにするため。

同じアカウントでログインし直すと、そのアカウントの枠だけが差し替わる。ログインは認可 URL に prompt=select_account を付けるので、必ずアカウント選択画面を経る（黙って前のアカウントを使わない）。login_hint を付けると、選択画面にはそのアカウントが提示される（2026-10-16 実機。別のアカウントが並ぶかはブラウザのセッション次第）。アカウントを消すには、その枠のディレクトリ（~/.config/drivelift/accounts/<email>）を削除する。削除用のツールは用意していない。

チームで使う場合

代表者が1人で OAuth クライアントを作り、ダウンロードした JSON をメンバーに配る運用ができる。

配るのは JSON だけ。 各メンバーは import_client_secret（または mv）で取り込み、auth_start で自分のアカウントでログインする。トークンは各自の手元にだけあり、代表者の権限で他人が操作することはない
Google Workspace なら同意画面は「内部」にする。 組織外のアカウントは認可できないので、JSON が外に漏れても組織外からは使えない。Google はデスクトップ種別の client_secret を秘密情報として扱わないが、配布はパスワード管理ツールや DM に留め、リポジトリには置かない
ファイルは各自のマイドライブに作られる。 共有したい相手には share で権限を付ける（例: 同じ組織の全員に閲覧権限なら {"role": "reader", "type": "domain", "target": "example.com"}）
チームの共有フォルダ（共有ドライブを含む）に置ける。 フォルダの ID を folder_id に渡せば、各自の drivelift がそこへ直接作る。ただし folder_path のサブフォルダはメンバーごとに別々に作られる（Aさんの drivelift が作ったフォルダは、Bさんの drivelift からは見えないため）。全員で同じ場所に集めたいときは、サブフォルダを手で作ってその ID を配り、folder_id で指定する
新しく作ったフォルダの URL を渡すなら share_new_folder を付ける。 付けないと、共有されるのはファイルだけで、フォルダは作った本人しか開けない
クライアントを作り直すと全員が invalid_client になる。 新しい JSON を配り直し、各自が取り込んで auth_start でログインし直すと、その枠のクライアントとトークンが差し替わる
プロジェクトの Owner を2人以上にしておく。 代表者の異動や退職でクライアントを管理できなくなるのを防ぐ
Drive API の上限はプロジェクト単位で全員が共有する。 通常の利用で問題になる量ではない

制約と注意

upload を常時許可すると、共有も常時許可したことになる。 share を使えば、1回の呼び出しで任意の外部アドレスやドメインに権限を付けられる（0.2.0 から）。ホストのツール許可で upload を「常に許可」にしている場合、プロンプトインジェクションでファイルを外部に共有される余地がある。0.1.0 で常に許可した人も、drivelift@0 を指定していれば自動で新しい版（0.2.0 以降。0.3.0 からは差し替え replace_id、0.4.0 からはフォルダ共有 share_new_folder も）に上がる。upload は MCP の注釈で破壊的操作（destructiveHint: true）と宣言している。気になる場合は upload を毎回確認する設定にする。share_new_folder も同じ扱いで、新しく作ったフォルダに限られるが、共有は以後そのフォルダに置くファイルにも及ぶ
folder_id には、ログインしたアカウントが編集できるフォルダなら何でも指定できる。drivelift が作っていないフォルダや共有ドライブ内のフォルダでもよい（2026-09-25 に共有ドライブで確認）。ただし drive.file の権限では、そのフォルダの中身は見えない。そのため folder_path で再利用できるのは drivelift が作ったフォルダだけで、他の人や手で作った同名フォルダがあっても、別に同名のフォルダを作る
同名ファイルがあっても上書きせず、新しいファイルを作る（Drive の既定どおり）。上書きは replace_id で ID を明示したときだけ
upload を常時許可していると、プロンプトインジェクションで drivelift が作ったファイルを別の中身に差し替えられる余地がある（replace_id、0.3.0 から）。drivelift が作ったもの以外には届かず、以前の版は版の履歴から戻せる
map_source と upload の account は、注入で送り先のアカウントを変えられる。 map_source の対応づけは、以後その到達元からの upload すべてに効く。付け替えは外す・追加するの 2 回に分けてあるが、map_source を常時許可していれば、どちらも確認なしで通る。upload を常時許可していれば、account 引数で別のアカウントへ送らせることもできる（到達元の対応づけと食い違えば、結果の mapped_to で分かる）。map_source は毎回確認する設定にしておく
ログイン済みのアカウントが 1 つのときは、対応づけが無くても従来どおり黙ってそのアカウントで送る。別案件のアカウントでしかログインしていなければ、そのアカウントに置かれる。2 つ目のアカウントでログインした時点で、対応づけの無い到達元からの upload は拒否されるようになる
token.json は暗号化していない。マシンを共有する環境では DRIVELIFT_CONFIG_DIR を保護された場所に向ける
Google Workspace の管理者がサードパーティアプリの API アクセスを制限している場合、「内部」クライアントでも認可できないことがある

開発

npm install
npm test
npm run build

テストは Google に接続しない（fetch を差し替え、ループバックのログインは実際のポートで検証する）。

ライセンス

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

drivelift

何を解くか

設計上の約束

導入

初回セットアップ

ツール

CLI

設定

0.4.0 からの移行

複数の Google アカウント

チームで使う場合

制約と注意

開発

ライセンス