GoogleDriveFilesystem

単一の Google Drive フォルダーにファイルを保存します。各ディレクトリは設定されたルート配下の Drive フォルダーに対応し、パスには POSIX の規則（例：/notes/todo.txt）を使用します。インターフェースの詳細は、WorkspaceFilesystem インターフェースを参照してください。

インストール

npm

npm install @mastra/google-drive

pnpm

pnpm add @mastra/google-drive

Yarn

yarn add @mastra/google-drive

Bun

bun add @mastra/google-drive

使用方法

Workspace に GoogleDriveFilesystem を追加して Agent に割り当てます。

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GoogleDriveFilesystem } from '@mastra/google-drive'

const workspace = new Workspace({
  filesystem: new GoogleDriveFilesystem({
    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
    accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
  }),
})

const agent = new Agent({
  id: 'drive-agent',
  name: 'Drive Agent',
  model: 'openai/gpt-5-mini',
  workspace,
})

認証

次の認証オプションのいずれかを指定します。

• accessToken：事前に取得した OAuth アクセストークン。認証済み ID と共有されたフォルダーをトークンから参照できるよう、https://www.googleapis.com/auth/drive スコープを使用します。
• getAccessToken：トークンを返すコールバック。外部でトークンを更新する場合に便利です。
• serviceAccount：Google サービスアカウント。対象フォルダーをサービスアカウントのメールアドレスと共有します。

サービスアカウント

バックエンド Agent にはサービスアカウント認証を推奨します。ユーザー同意フローやトークン更新処理は不要です。サービスアカウントの JSON キーファイルから必要なのは、client_email と private_key の2つの値だけです。

サービスアカウントを設定する

1. Google Cloud Console を開き、プロジェクトを選択または作成します。
2. APIs とサービス > ライブラリに移動し、Google Drive API を検索して有効にするを選択します。
3. APIs とサービス > 認証情報に移動し、認証情報を作成 > サービス アカウントを選択してフォームを入力します。ロールは空欄で構いません。Drive の権限は IAM ロールではなく、フォルダーの共有によって付与されます。
4. 新しいサービスアカウントを開き、キータブで鍵を追加 > 新しい鍵を作成 > JSONを選択します。ブラウザーに JSON キーファイルがダウンロードされます。
5. JSON ファイルから client_email の値をコピーします。Drive フォルダーはこのアドレスと共有します。

Drive フォルダーをサービスアカウントと共有する

サービスアカウントは独立した Google ID です。明示的に共有するまで、Drive 内の内容には一切アクセスできません。

1. Google Drive で対象フォルダーを開きます。
2. 共有を選択します。
3. サービスアカウントの client_email アドレスを貼り付けます。
4. 読み書きする場合は編集者、読み取り専用の場合は閲覧者にロールを設定し、送信を選択します。
5. URL からフォルダー ID をコピーします。https://drive.google.com/drive/folders/<folderId> の /folders/ より後の部分です。

警告

サービスアカウントは、通常の「マイドライブ」フォルダーにファイルを作成できません。サービスアカウントには個人用 Drive の保存容量がないため、作成するファイルは保存容量を持つ主体が所有する必要があります。個人用 Drive フォルダーを共有しただけの場合、読み取り操作は動作しますが、書き込みは容量エラーで失敗します。

書き込みアクセスには、フォルダーを共有ドライブ（旧 Team Drive）内に配置し、その共有ドライブのメンバーとしてサービスアカウントを追加します。共有ドライブは、サービスアカウントが作成するファイルに必要な保存容量を提供します。

個人用 Drive フォルダーに対する読み取り専用のワークロードには、この制限はありません。

Filesystem を設定する

JSON ファイルから client_email と private_key を環境へコピーします。

GOOGLE_DRIVE_FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz
GOOGLE_DRIVE_CLIENT_EMAIL=my-bot@my-project.iam.gserviceaccount.com
# Wrap the value in quotes — the key contains newlines that must be preserved.
GOOGLE_DRIVE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkq...\n-----END PRIVATE KEY-----\n"

import { GoogleDriveFilesystem } from '@mastra/google-drive'

const filesystem = new GoogleDriveFilesystem({
  folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
  serviceAccount: {
    clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
    privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
  },
})

JSON ファイル全体をコピーしたり、project_id、client_id、private_key_id、token_uri などの他のフィールドを渡したりする必要はありません。これらは使用されません。必須なのは clientEmail と privateKey だけです。privateKeyId、scopes、subject は任意です。scopes のデフォルトは ['https://www.googleapis.com/auth/drive'] で、サービスアカウントと共有されたフォルダーを参照するために必要なスコープです。より限定的な drive.file スコープでは、アプリケーション自身が作成したファイルにしかアクセスできないため、サービスアカウントと共有されたフォルダーは 404 Not Found を返します。

GoogleDriveFilesystem は署名の前に privateKey 文字列を自動的に正規化します。JSON でラップされた値のエスケープ済み引用符を含め、前後の引用符を取り除き、リテラルの \n シーケンスを実際の改行へ変換します。また、\r\n の改行コードを正規化し、末尾のカンマを削除します。.env ローダーが値をどのように処理しても、キーは機能します。

トラブルシューティング

• 404 File not found: <folderId>：サービスアカウントにフォルダーへのアクセス権がありません。フォルダーが正確な client_email アドレスと共有され、フォルダー ID が URL と一致していることを確認してください。
• 書き込み時の storageQuotaExceeded：フォルダーが個人用の「マイドライブ」にあります。フォルダーを共有ドライブへ移動し、サービスアカウントをメンバーとして追加してください。
• error:1E08010C:DECODER routines::unsupported：privateKey の値が不正です。値に完全な PEM ブロックが含まれ、改行が保持されていることを確認してください（リテラルの \n でも構いません）。

読み取り専用モード

書き込み操作（writeFile、appendFile、deleteFile、copyFile、moveFile、mkdir、rmdir）を禁止するには、readOnly: true を渡します。

const filesystem = new GoogleDriveFilesystem({
  folderId,
  accessToken,
  readOnly: true,
})

コンストラクターパラメーター

folderId:

string

Workspace のルートとして機能する Google Drive フォルダーの ID。すべてのパスはこのフォルダー内で解決されます。

accessToken?:

string

フォルダーへのアクセス権を持つ OAuth アクセストークン。

getAccessToken?:

() => string | Promise<string>

新しい OAuth アクセストークンを返すコールバック。認証が必要なリクエストごとに呼び出されます。

serviceAccount?:

{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }

OAuth 2.0 JWT フローでアクセストークンを発行するためのサービスアカウント認証情報。

id?:

string

= `google-drive:${folderId}`

この Filesystem インスタンスの一意な識別子。

readOnly?:

boolean

= false

true の場合、すべての書き込み操作を禁止します。

instructions?:

InstructionsOption

Tool の説明へ返すデフォルトの指示を上書きします。

プロパティ

id:

string

Filesystem インスタンスの識別子。

name:

string

Provider 名（'GoogleDriveFilesystem'）。

provider:

string

Provider 識別子（'google-drive'）。

readOnly:

boolean | undefined

Filesystem が読み取り専用モードかどうか。

メソッド

GoogleDriveFilesystem は WorkspaceFilesystem インターフェースを実装し、標準の Filesystem メソッドをすべて提供します。

• readFile(path, options?) - ファイル内容をダウンロード
• writeFile(path, content, options?) - ファイルをアップロードまたは上書き
• appendFile(path, content) - ファイルを読み取り、再アップロードして内容を追記
• deleteFile(path, options?) - ファイルを削除します
• copyFile(src, dest, options?) - Drive の files.copy API でファイルをコピー
• moveFile(src, dest, options?) - 親を差し替えてフォルダー間でファイルを移動
• mkdir(path, options?) - フォルダーを作成
• rmdir(path, options?) - フォルダーを削除
• readdir(path, options?) - フォルダー内容を一覧表示（recursive と extension による絞り込みに対応）
• stat(path) - ファイルまたはフォルダーの Drive メタデータを返す
• exists(path) - ファイルまたはフォルダーが存在するか確認

注意事項

• Google Drive では、同じフォルダー内に同名のファイルを複数配置できます。GoogleDriveFilesystem は最初に一致した項目を選んでパスを解決するため、パスベースの検索を利用する場合は、各フォルダー内で名前を一意にしてください。
• writeFile は、recursive が未設定（デフォルト）または true の場合に親フォルダーを自動作成します。親フォルダーが事前に存在することを必須にするには、recursive: false を設定します。
• WriteOptions の expectedMtime が適用されます。保存済みの modifiedTime と異なる場合、楽観的並行制御のため、書き込みは StaleFileError で拒否されます。
• Provider は組み込みの fetch を介して Drive REST エンドポイント（https://www.googleapis.com/drive/v3 と https://www.googleapis.com/upload/drive/v3）のみを使用します。追加の依存関係は不要です。