Skip to main content
Glama
gdrive-rag-mcp

gdrive-rag-mcp

by phamviet86

gdrive-rag-mcp

CI License: MIT

一个通过模型上下文协议(MCP)暴露的本地优先 Google Drive 混合索引。选择适合您的语言、隐私边界和基础设施的嵌入提供方和模型;然后从 Codex、Hermes Agent 或任何符合标准的 MCP 客户端查询同一持久索引。该索引不依赖于查询它的代理。

Google Drive/Workspace 仍然是只读的事实来源。该服务存储提取的块、归一化嵌入、元数据、校验和、同步状态和索引数据——而不是下载的源文件。它不需要 LlamaCloud,并且仅在可替换的分块边界使用 LlamaIndex。

重要提示: 检索仅辅助研究;不构成法律、税务、财务、经济或商业建议。代理和人员必须检查链接的来源、生效日期、司法管辖区和后续修订。如果 evidence.sufficient 为 false,请弃权而不是填补空白。

MVP 的功能

  • 使用只读 API 递归读取一个配置的 Drive 文件夹或共享云端硬盘范围。

  • 提取 Google 文档、Google 表格、文本/Markdown、基于文本的 PDF 和 DOCX。

  • 支持 Gemini、任何经过验证的兼容 OpenAI 的 /embeddings 端点,以及可选的本地 Sentence 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 分词器,而语义质量取决于模型和领域。请评估您的实际语言和文档;本项目不声称支持所有语言。

提供方

执行/隐私

多语言适用性

额外安装

备注

gemini(默认)

托管;块和查询发送到 Google 的嵌入 API

取决于模型;默认为多语言检索设计

无

向后兼容的提供方/模型/维度默认值

openai-compatible

托管或自托管;数据发送到配置的 base URL

取决于模型

无

实现文档化的 POST /embeddings JSON 契约;对于受信任的本地端点,API 密钥可能是可选的

sentence-transformers

模型下载后的本地进程/设备

选择并评估多语言检索模型

pip install 'gdrive-rag-mcp[sentence-transformers]'

重型 PyTorch/模型依赖不包含在基础安装中

更改嵌入提供方、模型、端点或维度需要重建该向量索引。更改 MCP 客户端或代理不需要重新索引。

HTTP 适配器遵循官方 OpenAI 嵌入请求/响应模式,包括批量字符串输入、有序结果、可选维度和浮点向量。不声称有专用的 Ollama 适配器。如果特定的 Ollama 部署明确实现了该 /v1/embeddings 契约,请将其作为兼容 OpenAI 的端点进行测试,如果该部署不接受 dimensions 字段,请设置 GDRIVE_RAG_EMBED_SEND_DIMENSIONS=false。

Gemini 使用检索特定的查询/文档任务和显式输出维度,如官方 Gemini 嵌入文档中所述。本地适配器使用文档化的 Sentence Transformers 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;请使用您的 shell 或进程管理器加载它。例如,在受信任的交互式 shell 中执行 set -a; . ./.env; set +a。切勿提交 .env。

配置嵌入提供方

密钥值来自 GDRIVE_RAG_EMBED_API_KEY_ENV 命名的环境变量。变量名是配置;密钥值永远不会存储在索引指纹或示例文件中。

Gemini(向后兼容默认值)

现有环境配置仍然有效:如果缺少提供方设置,服务将使用 Gemini、gemini-embedding-001、768 维和 GEMINI_API_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 中。仅当已验证的端点/模型不接受该可选字段时,才设置 GDRIVE_RAG_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_SERVICE_ACCOUNT_FILE 和 GDRIVE_FOLDER_ID。对于共享云端硬盘,请使用最低读取角色添加账户,并设置 GDRIVE_SHARED_DRIVE_ID。

除非单独审查,否则不要启用域范围委派。代码仅请求 https://www.googleapis.com/auth/drive.readonly。

用户 OAuth

  1. 创建 OAuth 桌面应用客户端,并将其 JSON 保存在存储库之外。

  2. 设置 GOOGLE_OAUTH_CLIENT_FILE 和 GOOGLE_OAUTH_TOKEN_FILE。

  3. 运行 gdrive-rag-mcp auth-google 一次并批准只读访问。

Drive API 没有“仅读取此现有文件夹”的 OAuth 范围。OAuth 令牌可以读取用户可读取的文件;索引器在遍历期间强制执行配置的文件夹。请参阅 Google 的 Drive 授权指南。

构建、刷新和迁移索引

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

定期运行 sync。它扫描选定的树,避免对未更改的校验和重新分块/重新嵌入,重新索引已更改的整个文件,删除过时的记录,并记录 completed_at。

嵌入指纹和旧索引

每个数据库记录提供方、模型、维度、端点标识和 SHA-256 指纹。MCP 状态工具返回提供方/模型/维度/指纹,但不暴露端点。

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 工具

所有工具名称和说明都是代理中立的,并标记为只读。

工具

用途

search_knowledge(query, limit)

混合搜索、引用、新鲜度和证据决策

get_document(document_id)

从有序块组装而成的完整索引文本

get_document_metadata(document_id)

URL、MIME 类型、校验和、修改/索引时间

check_index_status()

计数、上次同步、向量后端和嵌入指纹

弱命中放在 candidate_results 中用于诊断;当最高分低于 GDRIVE_RAG_EVIDENCE_THRESHOLD 时,正常的 results 保持为空。

本地模式(stdio)

gdrive-rag-mcp serve --transport stdio

客户端启动此进程。使数据库和提供方配置可用于该子进程。搜索需要提供方访问权限来获取查询嵌入;除非同一进程还执行同步,否则它永远不需要 Google 凭据。

Hermes Agent 本地 YAML

Hermes 从 ~/.hermes/config.yaml 读取 MCP 服务器,并支持环境变量替换。将实际密钥保存在 ~/.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 转发和远程 bearer 令牌密钥在官方 Codex MCP 指南中有文档说明。

服务器模式(Streamable HTTP)

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

端点为 http://127.0.0.1:8000/mcp;GET /health 是一个未经身份验证的存活检查,不返回索引详细信息。每个 /mcp 请求都需要 Authorization: Bearer ...。

在受信任的反向代理/负载均衡器处终止 TLS,保留 Authorization 标头,限制入站网络,并仅将应用程序绑定到代理网络。切勿暴露纯 HTTP 或将 bearer 令牌放在 URL 或存储库中。

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,并为硬件选择合适的镜像/运行时。对于单独的容器索引,请在 /data 下设置不同的 GDRIVE_RAG_DB_PATH 值。index-data 卷持久化 SQLite 数据。

Hermes Agent 远程 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 包含提取出的源文本。请加密磁盘/备份,并限制操作系统/卷的访问权限。

  • 托管的嵌入提供方会在同步期间收到提取的文本块,在搜索期间收到查询。请审查其数据条款和驻留要求。当数据不得离开主机时,请使用合适的本地模型。

  • API 密钥值只能来自环境变量。包含凭证的 Base URL 会被拒绝。

  • 指纹存储的是提供方/模型/维度/端点的身份,而不是 API 密钥。MCP 状态不会显示该端点。

  • 轮换 MCP、Google 和嵌入提供方的凭证,并在轮换后重启。

  • 工具仅用于检索;Drive 写入和索引变更不会通过 MCP 暴露。

  • 有关漏洞报告和部署加固,请参阅 SECURITY.md。

坦诚的局限性

  • 纯扫描/纯图片 PDF 需要先进行 OCR 才能建立索引;本项目不执行 OCR。

  • Sheets 会索引显示的单元格值和工作表名称,而不是图表、批注或公式逻辑。

  • Docs 的批注、建议、修订历史、链接文件和富版式不会被保留。

  • Slides、图片、音频、视频、快捷方式和任意二进制格式会被跳过。

  • 同步是对文件夹树进行扫描,而不是使用 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 文件夹、嵌入 provider/model 和 secret。

  3. 选择你已经评估过越南语质量的模型,然后运行 gdrive-rag-mcp sync。

  4. 运行 stdio 或 HTTP MCP,并使用任何兼容的 MCP 客户端连接。更换智能体无需重新建立索引;更换 provider/model/dimensions 时,请运行 gdrive-rag-mcp reindex --yes 或使用其他 profile/database。

  5. 当 evidence.sufficient=false 时,智能体必须拒绝下结论;始终打开 Drive 来源,检查生效日期并引用来源。

许可证

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers