Mcp Gdrive Cloudflare

mcp-gdrive-cf

运行于 Cloudflare Workers 上的 Google Drive 和 Sheets 远程 MCP 服务，完整支持 OAuth 2.0。

生产就绪 ✅ | 11 个工具 | OAuth 2.0 | PKCE | 全球边缘网络

本项目改编自 isaacphi/mcp-gdrive，可在 Cloudflare 边缘网络上作为远程 HTTP/SSE MCP 服务运行，并具备完整的 OAuth 2.0 授权服务器功能。

---

🚀 快速开始

```bash

1. 克隆并安装

git clone https://github.com/brianmoney/mcp-gdrive-cf.git cd mcp-gdrive-cf npm install

2. 创建 KV 命名空间

wrangler kv:namespace create KV_TOKENS wrangler kv:namespace create KV_CLIENTS

3. 使用你的命名空间 ID 更新 wrangler.toml

4. 配置 Google OAuth 凭据

wrangler secret put GOOGLE_CLIENT_SECRET

5. 部署

wrangler deploy

6. 使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector https://your-worker.workers.dev/sse ```

---

✨ 功能

Drive 操作

• 🔍 搜索 - 基础和高级搜索，支持筛选条件（MIME 类型、所有者、日期、共享云端硬盘）
• 📄 读取 - 读取任意文件，支持 22 种以上的导出格式（PDF、DOCX、XLSX、Markdown 等）
• 📁 创建文件夹 - 使用嵌套文件夹结构整理文件
• ⬆️ 上传 - 上传最大 5MB 的文件
• 🗑️ 删除 - 将文件移至垃圾箱
• 📦 移动 - 在文件夹之间重新整理文件
• 🔐 共享 - 添加权限（阅读者、写入者、评论者、所有者）

Sheets 操作

• 📊 读取 - 批量读取多个范围
• ✏️ 更新 - 更新单个单元格
• ➕ 追加 - 向电子表格添加行

基础设施

• ☁️ 全球边缘网络 - 在全球各地的 Cloudflare Workers 上运行
• 🔐 OAuth 2.0 服务器 - 完整的授权服务器，支持 PKCE
• 🔑 动态客户端注册 - 自动接入客户端
• 🔄 自动刷新令牌 - 无缝续期 Google 令牌
• 📡 SSE 传输 - 实时服务器发送事件
• 🛡️ 安全 - 仅支持 HTTPS，令牌加密存储

---

🎯 有何不同

与原始的基于 STDIO 的 `mcp-gdrive` 不同，本实现：

1. 远程运行于 Cloudflare Workers（无需本地进程）
2. 提供完整的 OAuth 2.0 授权服务器（不只是 OAuth 客户端）
3. 通过动态客户端注册支持多个客户端
4. 为公共客户端提供 PKCE 安全保护
5. 支持 Drive 文件的 22 种以上导出格式
6. 支持写入操作（创建、删除、移动、共享、上传）
7. 已通过真实工作负载的生产环境测试

---

📋 前提条件

必需

• 已启用 Workers 的 Cloudflare 账户（免费套餐即可）
• 已启用 Drive API 和 Sheets API 的 Google Cloud 项目
• Node.js LTS（v18+）
• Wrangler CLI（`npm install -g wrangler`）

Google Cloud 设置

1. 在 Google Cloud Console 创建项目
2. 启用 API：
   • Google Drive API
   • Google Sheets API
3. 创建 OAuth 2.0 凭据：
   • 类型：Web 应用
   • 重定向 URI：`https://your-worker.workers.dev/google/callback\`
4. 所需的 OAuth 范围：
   • `https://www.googleapis.com/auth/drive\`
   • `https://www.googleapis.com/auth/spreadsheets\`

---

🔧 安装与部署

1. 安装依赖

```bash npm install ```

2. 创建 KV 命名空间

```bash

用于用户会话令牌

wrangler kv:namespace create KV_TOKENS

用于 OAuth 客户端注册

wrangler kv:namespace create KV_CLIENTS ```

将命名空间 ID 复制到 `wrangler.toml`：

```toml [[kv_namespaces]] binding = "KV_TOKENS" id = "your-tokens-namespace-id"

[[kv_namespaces]] binding = "KV_CLIENTS" id = "your-clients-namespace-id" ```

3. 配置环境变量

添加到 `wrangler.toml`：

```toml [vars] GOOGLE_CLIENT_ID = "your-client-id.apps.googleusercontent.com" ```

设置密钥：

```bash

Google OAuth 客户端密钥

wrangler secret put GOOGLE_CLIENT_SECRET ```

4. 部署

```bash wrangler deploy ```

你的 Worker 将可通过此地址访问：`https://your-worker-name.your-account.workers.dev\`

---

🔐 OAuth 2.0 流程

此服务根据 MCP 规范实现了完整的 OAuth 2.0 授权服务。

使用 MCP Inspector

测试 OAuth 流程的最简单方式：

```bash npx @modelcontextprotocol/inspector https://your-worker.workers.dev/sse ```

1. 发现 - Inspector 自动发现 OAuth 端点
2. 注册 - 点击“引导设置” → 自动注册客户端
3. 授权 - 重定向到 Google → 完成身份验证 → 重定向回来
4. 令牌交换 - 自动将授权码兑换为访问令牌
5. 使用工具 - 现在即可使用全部 11 个工具！

安全功能

• ✅ PKCE（RFC 7636） - 代码交换证明密钥
• ✅ State 参数 - CSRF 防护
• ✅ 仅限 HTTPS - 由 Cloudflare Workers 强制执行
• ✅ 安全的令牌存储 - 在 Workers KV 中加密存储
• ✅ 令牌过期 - 访问令牌 1 小时后过期
• ✅ 客户端密钥哈希 - 使用 SHA-256 哈希存储
• ✅ 授权码仅限单次使用 - 兑换后删除授权码

---

🛠️ 可用工具

Drive 工具

• `gdrive_search` - 搜索所有文件
• `gdrive_search_advanced` - 使用筛选条件进行高级搜索
• `gdrive_read_file` - 以 22 种以上格式导出并读取文件
• `gdrive_create_folder` - 创建文件夹
• `gdrive_upload_file` - 上传文件（最大 5 MB）
• `gdrive_delete_file` - 将文件移至回收站
• `gdrive_move_file` - 在文件夹之间移动文件
• `gdrive_add_permission` - 共享文件/文件夹

Sheets 工具

• `gsheets_read` - 读取多个范围
• `gsheets_update_cell` - 更新单元格
• `gsheets_append_row` - 追加行

---

🔌 客户端配置

VS Code MCP 扩展

创建 `.vscode/settings.json`：

```json { "mcp.servers": { "gdrive": { "url": "https://your-worker.workers.dev/sse", "authorization": { "type": "oauth2" } } } } ```

Claude Desktop / Cline

macOS/Linux： `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows： `%APPDATA%\Claude\claude_desktop_config.json`

```json { "mcpServers": { "gdrive": { "url": "https://your-worker.workers.dev/sse" } } } ```

---

🧪 测试

本地开发

```bash npm start

服务可通过 http://localhost:8788 访问

```

使用 MCP Inspector 测试

```bash npx @modelcontextprotocol/inspector http://localhost:8788/sse ```

查看 CloudFlare 日志

```bash wrangler tail --format pretty ```

---

🐛 故障排除

“Failed to discover OAuth metadata”

解决方案：

• 确保 `/.well-known/oauth-authorization-server` 返回有效的 JSON
• 检查是否包含 CORS 标头
• 确认已部署最新版本：`wrangler deploy`

“Token exchange failed: HTTP 400”

解决方案：

• 检查 code_verifier 是否与原始 code_challenge 匹配
• 确保 redirect_uri 与注册时完全一致
• 确认客户端凭据正确
• 查看 CloudFlare 日志：`wrangler tail`

工具无法使用

解决方案：

• 检查 Google OAuth 范围是否包含 `drive` 和 `spreadsheets`
• 如果范围发生变化，请重新进行身份验证：访问 `/google/authorize`
• 确认 Worker 拥有有效的 Google 访问令牌
• 检查 `wrangler.toml` 中的 KV 命名空间绑定

---

📊 性能与限制

资源	限制	说明
请求超时	30 秒	CloudFlare Workers 限制
文件上传	5 MB	简单上传 API 限制
文件导出	10 MB	Google Drive 导出限制
令牌存储	30 天	自动清理
授权码	10 分钟	仅限单次使用
访问令牌	1 小时	自动刷新

---

🔒 安全最佳实践

1. 切勿提交密钥 - 使用 `wrangler secret put`
2. 轮换客户端密钥 - 定期重新生成 OAuth 凭据
3. 监控访问情况 - 使用 CloudFlare Analytics 跟踪使用情况
4. 限制 OAuth 作用域 - 仅请求必要的 Google 权限
5. 使用 PKCE - 公共客户端始终使用 PKCE
6. 验证重定向 URI - 在 Google Console 中将精确的 URI 加入白名单
7. 启用 2FA - 保护你的 CloudFlare 和 Google 账户

---

📄 许可证

MIT 许可证

---

🙏 致谢

• isaacphi/mcp-gdrive - 原始 STDIO 实现
• Model Context Protocol - MCP 规范
• CloudFlare Workers - 无服务器平台

---

由 Brian Money 用 ☁️ 制作