gdrive-rag-mcp

[(LICENSE)

Model Context Protocol (MCP) を介して公開する、ローカルファーストの Google Drive ハイブリッド・インデックスです。言・言葉、プライバシー境界、インフラを基盤に合ったエンベディング・プルバイダとモデルを選択し、その同じ永続インデックスを Codex、Hermes Agent、または標準準拠の MCCP クライアントからクエリできます。インデックスは、それをクエリするエージェントと結び付いません。

Google Drive/Works个人 は読み取専用の情情報源 (source of truth) のままです。このサビースは、抽出したチャンク、正規化されたエンベディング、メタデータ、チェックサム、同期状態、インデックス・データを保存し、ダウンロードしたソースファイルは保存しません。LlamaCloud は不用で、LlamaIndex は置き換え可能なチャンキング限境でのみ使います。

**重 **: リトリーall (検索) は研究を助けるためのもので、法的・税務・財務・経済・ビジネス上の助言ではありません。エージェントと利用者は、リンクされたソース・発効点・適用不可・後の改正を必ず確認して下さい。evidence.sufficient が false である場合は、不足を差し埋めるのでなく、「差し控え」を選んでください。

MVP の機能

• 読み取り専用一个一回API をして、設定した 1つの Drive フォルダまたは Shared Drive のスコープを再起的にります。

• Google Docs、Google Sheets、テキスト/Markdown、テキストバースの PDF、DOCX を抽出します。

• Gemini と検証済みの、OpenAI 互換の /embeddings エンドポイント、およびオプションのローカル Senence Transformers を、単一のエンベディング・プロトコルでサポートします。

• Unicode 対エの SQLite FTS5 キーワード検索と sqlite-vec コサイン検索とを組み合わせます。拡張がない場合には、テスト済みの Python コサイン代替を実行します。

• 変更されたファイルを再インデックス化し、後の同期で削除されたファイル・対象外ファイルをインデックス対象から除去します。

• プロバイダー、モデル、エンドポイント、次元の異なるベクトルが同一インデックスを共有しないよう、エンベディグ・フィンガープリントを記録・検証します。

• 引用、ソースの更新時刻・取込み時刻、および保守的なエビデンス判定を返します。

• 同し読み取専用ツールを、ローカル stdio とBearer 保護された Streamable HTTP の両方で公開します。

Related MCP server: google-workspace-mcp-server

アーキテクチャ

flowchart LR
    D[Selected Google Drive scope] -->|read-only Drive API| X[Format extractors]
    X --> L[LlamaIndex chunking boundary]
    L --> E{Embedding provider}
    E -->|Gemini| V[Normalized vectors]
    E -->|OpenAI-compatible HTTP| V
    E -->|Local Sentence Transformers| V
    L --> S[(SQLite documents + FTS5)]
    V --> Q[(sqlite-vec / cosine fallback)]
    S --> R[Hybrid ranking + evidence gate]
    Q --> R
    R --> M[Agent-neutral MCP tools]
    M --> A[Any compatible MCP client]

Google、エンベディング・プロバイだー、ローカル・モデルの認証情報とリソースは、サービスの運営側に留まります。リモートのクライアントが受け取るのは、MCP URL と Bearer トールンだけです。

エンベディング・プロバイダー

言語カバレッジは、選んだモデル固有性です。インデックスに「言語モード」はありません。FTS5 は SQLite の Unicode トークナイザーをを使い、意味の質はモデルととドメインに依ります。実際の言語とドキュメントを評価してください。このツールがすべての言語の完璧な対応を主張るするもではありません。

エンベディグ・プロバイだ、モデル、エンドポイント、次元を変更場合は、そのベクトル・インデックスで再構築が要です。MCP クライアントを変更して、エージェントを変更する場合は、再インデックス化は不要 です。

HTTP アダプターは、POST /embeddings の組織的にバッチ文字列・入力の順を保持結果、任意の次元、floating point ベクトルなどを含む、情報な公開されない official OpenAI embeddings のAP I スキマに従います。

専用の Ollama アダプターの提唱はしていません。特定の Ollama の導入物が、その /v1/embeddings コントラクトを明確に実装する場合、OpenAI互換のエンドポイントとしてテストし、その導入物が dimensions フィールドを受付けなければ、GRIVE_AG_EMBED_SEND_DIMENSIONS=false に設定してください。

Gemini は、公式 Gememi のエンベディングのドキュメントに記述る、検索専用のクエリ/ドキュメント・タスクと、明確な出次元を使い、ページ 次の com.uk を参照する。ローカルアーダターは、正規化された出カとともに、公式の記述ある encode_query と encode_document のメソッド をし用。

インストール

git clone https://github.com/phamviet86/gdrive-rag-mcp.git
cd gdrive-rag-mcp
python3.12 -m venv .venv
. .venv/bin/activate
pip install -e .
cp .env.example .env

ローカル・プロバイダーときは、インストールは pip install -e '.[sentence-transformers]' で行います。本プロジェクトは .env を自動で読でません。シェルまたはプロセス・マで読込みんでください。例: set -a; . ./.env; set -a を安全な対話シェルで実行。.env をコミットしては行けません。

エンベディング・プロバイダーの設定

シークレット値は、構成 GRIVE_AG_EMBED_AP_IKE_Y_V で参照される環境変数から取り出します。この変数名は設定部であり、シークレット値はインデックス・フィンガープリントやサンプルに保存される決してありません。

ジェミニ (後方互換のデフォルト)

既存の設定構成は有効: プロバイダー設定がなければ、サービスは Gemini、gemini-embedding-001、768 次元、および GEMINI_AP_I_KEY をです。

export GDRIVE_RAG_EMBED_PROVIDER=gemini
export GDRIVE_RAG_EMBED_MODEL=gemini-embedding-001
export GDRIVE_RAG_EMBED_DIMENSIONS=768
export GDRIVE_RAG_EMBED_API_KEY_ENV=GEMINI_API_KEY
export GEMINI_API_KEY=your_runtime_secret

OpenAI 互換のエージェント

export GDRIVE_RAG_EMBED_PROVIDER=openai-compatible
export GDRIVE_RAG_EMBED_MODEL=text-embedding-3-small
export GDRIVE_RAG_EMBED_DIMENSIONS=1536
export GDRIVE_RAG_EMBED_BASE_URL=https://api.openai.com/v1
export GDRIVE_RAG_EMBED_API_KEY_ENV=OPENAI_API_KEY
export OPENAI_API_KEY=your_runtime_secret

互換のエンドポイントへ変更る場合は、base URL、モデル、次元、キー変数環境数を新しく指定します。base URL に認証は入れ決して入れ。検証済みエンドポイント/モデルがその optional フィールド (dimension) を受けない場合のみ、GRIVE_AG_EMBED_SEND_DIMENSIONS=false を指定します。設定した出力次元は、どのレスポンスんで検証され続ます。

ローカル Sentence Transformers

pip install -e '.[sentence-transformers]'
export GDRIVE_RAG_EMBED_PROVIDER=sentence-transformers
export GDRIVE_RAG_EMBED_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
export GDRIVE_RAG_EMBED_DIMENSIONS=384
export GDRIVE_RAG_EMBED_DEVICE=cpu  # or a device supported by your local installation

上の名モデルは一つの例で、済普遍的推推奨ではなりません。上の名モデルのマンロード、キャシュ、ライセンス、言語の網、メモリの使用、ハードウ应の条件は、選択したモデルの側にあります。通常の在調性?

export GDRIVE_RAG_EMBED_BATCH_SIZE=32
export GDRIVE_RAG_EMBED_TIMEOUT_SECONDS=60

全プロバイダーとも、正規イのベクトルを戻し、設定済済みの次元数をちようど返すことがいます。

Google 認証

Google Drive API を有効化してから、どちらか方法を選びください。

サービアカウント (最小権限度限の推奨)

1. サービスアカウントを作成し、その JSON キーを運用者専用の秘密フォルダーに置きします。

2. 選択したしだDriveフォルにだけ、そのメールと ビューアーとして共有する。これによって、ユーザーの OAuth トークンより強固なフールダ境界を確立できます。

3. GOOGLE_SYSTEM_A_FILE と GDRIVE_FOLDER_ID を設定します。Shared Drive の場合、アカウントを読取み役割で追加し、GDRIVE_SHARED_DRIVE_ID を設定します。

ドメイン側の委任は、別途検討なしない限り有効化しないでください。本コマンドが要求するスコープは、https://www.googleapis.com/auth/drive.readonly のみです。

ユーザーOAuth

1. OAuth デスクトップ・アプリのクライアント (OAuth client)、その JSON をレポジトリの外で保持します。

2. GOOGLE_O_AUTH_CLIENT_FILE と GOOGLE_O_AUTH_TOKEN_FILE を設定します。

3. gdrive-ag-mcp auth-* を1回だけ実行し、読み取り専用アクセスを承認してください。

Drive API に既存フォルダだけの読取という OAuth スコープありません。OAuth トークンは、ユーザーが読取れるファイルを読めます。インデックサーは走査の時、設定フォルダを適用します。Google の [Drive 認証挙動ガイド](https://developers.google.com/workspace/drive/api/guidees api専) を参照願います。

インデックスの構築・更新・移行

gdrive-rag-mcp init-db
gdrive-rag-mcp sync
gdrive-rag-mcp status

sync を定期的に実行します。指定のツリーをスキャ、検査サムが変らないものの再チャンク化・再ンベディングかを避け、変更あファイルをチャンク全体で再読取り、公式ていないレコードを消します。削除し、最後の完了::時刻を記録します。

Embedding フィンガープリント、旧版インデックス

各データベースはプロバイだーモモデル・次元・エンドポイントの識別と SHA-256 フィンガープリントを記録します。MCP ステータス・ツールが provider/model/dimensions/フィンガープリントを返し、エンドポイントは反しません。

バージン 0.1.x は、古いデフォルトの Gemini をインストールしていても、謎別子を記録したでいに。空でない旧インデックスは確実には推定ないため、0.2 はそれを開くこを拒否します。データベースを希望するだけバックアップし、同じ Drive とプロバイダの認証情報をむろ込んで、明に再構築してくださ:

gdrive-rag-mcp reindex --yes

このコマンドは、選択のデータベースの生成済みインデックスだけを削除し、完全に Drive 同期をします。Drive 側を変更ることはありません。空の旧データベースは自動的にスタンプを押されます。

複数の意的インデックスを保持るには、名前付きプロファイルあるいは明示的なパスを使います:

GDRIVE_RAG_INDEX_PROFILE=gemini gdrive-rag-mcp sync
GDRIVE_RAG_INDEX_PROFILE=local-multilingual gdrive-rag-mcp sync
# Or set GDRIVE_RAG_DB_PATH explicitly for complete path control.

デフォルトのプロファイルは後方互換の data/index.db を保持。他はプルロ完成に data/index-<profile>.db を生成します。

MCP ツール

すべてのツールン名・説明は、エージェントに依存しない読み取り専用と明記しています。

弱い一致は、診断に candidate_results に置されます。results は、トップ score が GRDIVE_RAG_EVIDENCE_THRESHOLD マイ下の場合は空のままです。

ローカル モード (STDIO)

gdrive-rag-mcp serve --transport stdio

クライアントがこのプロセスを起動します。データベースとプロバイダー設定を、そのサブプロセスから参照できるようにします。検索はクエリのエンベディング时のみプロバイダ・アクセスはるであり、同期を同じプロセスで行わなければ、Google の認証は必要ありません。

Hermes Agent ローカル YAML

Hermes は、MCP サーバを ~/.hermes/config.yaml から読み、環境変数の代入に対応。 ~/.hermes/.env が直近の環境に実際の秘密を置きます。

mcp_servers:
  gdrive_knowledge:
    command: "/path/to/gdrive-rag-mcp/.venv/bin/gdrive-rag-mcp"
    args: ["serve", "--transport", "stdio"]
    env:
      GDRIVE_RAG_DB_PATH: "${GDRIVE_RAG_DB_PATH}"
      GDRIVE_RAG_EMBED_PROVIDER: "${GDRIVE_RAG_EMBED_PROVIDER}"
      GDRIVE_RAG_EMBED_MODEL: "${GDRIVE_RAG_EMBED_MODEL}"
      GDRIVE_RAG_EMBED_DIMENSIONS: "${GDRIVE_RAG_EMBED_DIMENSIONS}"
      GDRIVE_RAG_EMBED_API_KEY_ENV: "${GDRIVE_RAG_EMBED_API_KEY_ENV}"
      GEMINI_API_KEY: "${GEMINI_API_KEY}"
    timeout: 120
    connect_timeout: 30
    supports_parallel_tool_calls: true

最後のシークレット変数を指定のプロバイダーにあるものに置き換えてください。形式は 公式 Hermes MCP ガイド に基づきます。

Codex ローカルTOML

~/.codex/config.toml または信頼できるプロジェクトの .codex/config.toml へ追加してください:

[mcp_servers.gdrive_knowledge]
command = "/path/to/gdrive-rag-mcp/.venv/bin/gdrive-rag-mcp"
args = ["serve", "--transport", "stdio"]
cwd = "/path/to/gdrive-rag-mcp"
env_vars = [
  "GDRIVE_RAG_DB_PATH",
  "GDRIVE_RAG_EMBED_PROVIDER",
  "GDRIVE_RAG_EMBED_MODEL",
  "GDRIVE_RAG_EMBED_DIMENSIONS",
  "GDRIVE_RAG_EMBED_BASE_URL",
  "GDRIVE_RAG_EMBED_API_KEY_ENV",
  "GEMINI_API_KEY",
  "OPENAI_API_KEY",
]
startup_timeout_sec = 30
tool_timeout_sec = 120
required = true

Codex の現在の stdio 転送とリモートベアラートークン鍵は 公式Codex MCP ガイド に文書化されています。

サーバーモード (Streamable HTTP)

export GDRIVE_RAG_BEARER_TOKEN="$(openssl rand -hex 32)"
gdrive-rag-mcp serve --transport http

エンドポイントは http://127.0.0.1:800/mcp で、GET /health は認証不要のライブネス応答です、インダックスの情報を表しません。 /mcp へのリクエストには、常に Authorization: Bearer ... が必要です。

Docker Compose

べースのイメージは Gemini と HTTP プロバイだーを含みますが、PyTorch/Sentence Transformers は含組みせん。

mkdir -p secrets
# Place service-account.json in secrets/; this directory is ignored.
export GDRIVE_FOLDER_ID=your-folder-id
export GDRIVE_RAG_BEARER_TOKEN="$(openssl rand -hex 32)"
export GDRIVE_RAG_EMBED_PROVIDER=gemini
export GDRIVE_RAG_EMBED_API_KEY_ENV=GEMINI_API_KEY
export GEMINI_API_KEY=your-runtime-secret
docker compose run --rm app sync
docker compose up -d app

ローでは Sentence Transformers 利用する場合は、ビルド前に GDRIVE_RAG_EXTRAS=sentence-transformers と設定し、ハードウエアに合うイメージ/ランタイムを選びます。コンテナ別にインデックスを持たせる場合は、/date の下に一連の異る GRIVE_RAG_DB_PAH 値を設定します。index-data ボリュームに SQLite のデータが永続されます。

Hermes Agent にLees リモート YAML

mcp_servers:
  gdrive_knowledge:
    url: "https://knowledge.example.com/mcp"
    headers:
      Authorization: "Bearer ${GDRIVE_RAG_BEARER_TOKEN}"
    timeout: 120
    connect_timeout: 30
    supports_parallel_tool_calls: true

Codex リモート TOML

[mcp_servers.gdrive_knowledge]
url = "https://knowledge.example.com/mcp"
bearer_token_env_var = "GDRIVE_RAG_BEARER_TOKEN"
startup_timeout_sec = 30
tool_timeout_sec = 120
required = true

汎用 MCP クライアント

MCP設定ファイルの構文はクライアント固有です。標準準拠のクライアントは、次のいずれかを使用できます：

• stdio：コマンド gdrive-rag-mcp、引数 serve --transport stdio、およびオペレーターのインデックスと埋め込み環境変数

• Streamable HTTP：URL https://knowledge.example.com/mcp とヘッダー Authorization: Bearer $GDRIVE_RAG_BEARER_TOKEN

サーバーはGoogleや埋め込みプロバイダーの認証情報をクライアントに公開しません。OpenClawや、ここで検証済みのネイティブ形式を持たない他のエージェントの場合は、検証されていないクライアント固有のスニペットをコピーするのではなく、標準準拠のMCPアダプターをこれらのトランスポート値で設定してください。

セキュリティとデータの取り扱い

• .env、データベース、OAuthトークン、クライアントシークレット、サービスアカウントキー、ダウンロードしたファイル、モデルキャッシュ、生成されたインデックスは、ソース管理の外に置く必要があります。

• SQLiteには抽出されたソーステキストが含まれます。ディスク/バックアップを暗号化し、OS/ボリュームへのアクセスを制限してください。

• ホスト型埋め込みプロバイダーは、同期中に抽出されたチャンクと、検索中のクエリを受け取ります。データの利用条件と保存場所を確認してください。データをホスト外に出すことができない場合は、適切なローカルモデルを使用してください。

• APIキー値は環境変数からのみ取得されます。認証情報を含むベースURLは拒否されます。

• フィンガープリントはプロバイダー/モデル/ディメンション/エンドポイントの識別情報を保存し、APIキーは保存しません。MCPステータスはエンドポイントを省略します。

• MCP、Google、埋め込みプロバイダーの認証情報をローテーションし、ローテーション後に再起動してください。

• ツールは取得専用です。Driveへの書き込みとインデックスの変更はMCPを通じて公開されません。

• 報告とデプロイの強化については SECURITY.md を参照してください。

正直な制限事項

• スキャンされた画像のみのPDFは、インデックス作成前にOCRが必要です。このプロジェクトはOCRを実行しません。

• スプレッドシートは表示されたセル値とシート名をインデックスします。チャート、コメント、数式ロジックはインデックスしません。

• Docsのコメント、提案、改訂履歴、リンクされたファイル、リッチレイアウトは保持されません。

• スライド、画像、オーディオ、ビデオ、ショートカット、任意のバイナリ形式はスキップされます。

• 同期はフォルダツリースキャンであり、Drive Changes APIではありません。変更は次の同期の成功後に表示されます。

• 検索スコアはヒューリスティックであり、確率ではありません。高リスクの使用前に、ドメイン固有の多言語評価で証拠のしきい値を調整してください。

• FTSトークン化はUnicode対応ですが、言語固有の形態素解析器ではありません。空白のない言語や複雑なセグメンテーションを持つ言語は、意味的検索に大きく依存する可能性があります。

• SQLiteは小規模な共有サービスに適していますが、高書き込みや大規模な分散ワークロードには適していません。永続化と取得は分離されているため、後で置き換えることができます。

開発

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
ruff format --check .
ruff check .
mypy src/gdrive_rag_mcp
pytest

テストはフェイクソース、HTTPトランスポート、決定的なUnicode対応埋め込みを使用します。Google、Gemini、OpenAI、またはローカルモデルの認証情報は不要です。CONTRIBUTING.md を参照してください。

ベトナム語によるクイックスタート

これはコミュニティの例です。プロジェクトは特定の言語をデフォルトにしていません。意味検索の品質は選択した埋め込みモデルに依存します。

1. サービスアカウントを作成し、Google Drive APIを有効にし、インデックスを作成するフォルダのみをViewer権限で共有します。

2. .env.example を .env にコピーし、環境変数でDriveフォルダ、埋め込みプロバイダー/モデル、シークレットを設定します。

3. ベトナム語の品質を評価したモデルを選択し、その後 gdrive-rag-mcp sync を実行します。

4. stdioまたはHTTP MCPを起動し、互換性のあるMCPクライアントで接続します。エージェントを変更しても再インデックスは不要です。プロバイダー/モデル/ディメンションを変更する場合は、gdrive-rag-mcp reindex --yes を実行するか、別のプロファイル/データベースを使用します。

5. evidence.sufficient=false の場合、エージェントは結論を拒否しなければなりません。常にDriveのソースを開き、有効日と引用を確認してください。

ライセンス

MIT