Google MCP Remote

Google MCP Remote

这是一个基于 Cloudflare Workers 的 MCP 服务实现，为 Model Context Protocol 提供 Google API 工具（Gmail、Calendar、Drive 等），旨在与 Claude 或 Cursor 等 AI 客户端无缝集成。

⚠️ 安全警告：请勿使用他人部署的此服务实例，因为它需要访问你的 Google 账号和个人数据。请务必部署自己的实例，以便掌控自己的数据和 API 访问权限。

功能

• Gmail：
  • 向多个收件人（to、cc、bcc）发送邮件，并支持 HTML 内容
  • 使用自定义查询、标签和结果数量上限列出邮件
  • 按 ID 读取指定邮件
  • 管理标签（添加、移除、列出）
  • 创建草稿和删除邮件
• Calendar：
  • 列出日历并设置默认日历
  • 创建包含详细信息的活动（摘要、开始／结束时间、参与者等）
  • 使用可自定义的筛选条件列出即将发生的活动
  • 更新或删除已有活动
  • 查找可用于安排日程的空闲时段
• Drive：
  • 使用搜索查询筛选文件
  • 按修改日期或其他条件排序
  • 查看详细的文件元数据
  • 读取文件内容（文本、文档、电子表格）
  • 创建包含指定内容的新文件
  • 更新已有文件
  • 删除文件（移至垃圾桶或永久删除）
  • 使用特定权限共享文件
• Tasks：
  • 查看所有任务列表
  • 创建新任务列表
  • 删除已有任务列表
  • 使用筛选条件列出任务
  • 查看任务详情
  • 创建包含标题、备注和截止日期的任务
  • 更新任务属性
  • 将任务标记为已完成
  • 删除任务
• YouTube：
  • 使用可自定义的参数搜索视频
  • 获取指定视频的详细信息
• Contacts：
  • 列出并搜索 Google Contacts 中的联系人
  • 获取指定联系人的详细信息

部署说明

前提条件

1. Google Cloud 项目：

   • 在 Google Cloud Console 中创建项目

   • 设置 OAuth 2.0 凭据（Client ID 和 Client Secret）

   • 启用所需的 API（Gmail、Calendar、Drive、Tasks、YouTube、People／Contacts）

   • 为你的 Cloudflare Worker 添加已获授权的 JavaScript 来源和重定向 URI

   • 重定向 URI 应采用以下格式：

     已部署的网址 + /callback
      https://your-project.your-username.workers.dev/callback
     
     用于本地测试：
      http://localhost:8788/callback
     

2. Cloudflare 账号：

   • 如果还没有 Cloudflare 账号，请注册一个
   • 安装 Wrangler CLI：bun install -g wrangler
   • 使用 Cloudflare 进行身份验证：wrangler login

部署步骤

1. 克隆代码仓库：

   git clone https://github.com/vakharwalad23/google-mcp-remote.git
   cd google-mcp-remote
   

2. 安装依赖项：

   bun install
   

3. 配置密钥： 在 Cloudflare 中将 Google OAuth 凭据设为密钥：

   wrangler secret put GOOGLE_OAUTH_CLIENT_ID
   wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET
   wrangler secret put COOKIE_ENCRYPTION_KEY
   

   （对于 COOKIE_ENCRYPTION_KEY，请生成一个随机字符串来保护 Cookie）

4. 创建 KV 命名空间：

   wrangler kv:namespace create OAUTH_KV
   

   然后使用输出中的 ID 更新 wrangler.jsonc

5. 部署到 Cloudflare Workers：

   bun run deploy
   

6. 记下部署网址： 部署完成后，Wrangler 会提供类似 https://your-project.your-username.workers.dev 的网址

与 AI 客户端搭配使用

部署完成后，配置你的 AI 客户端（Claude、Cursor 等）以使用你的 MCP 服务。

Claude 配置

编辑你的 claude_desktop_config.json，或者对于 Cursor，编辑 mcp.json：

{
  "mcpServers": {
    "google-mcp-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-project.your-username.workers.dev/sse"
      ]
    }
  }
}

示例命令

现在，你可以让 Claude 使用你的 Google 账号执行任务：

Send an email to [email protected] with the subject "Meeting Notes" and body "Here are the notes from today."

List my upcoming calendar events for the next 3 days.

Create a calendar event titled "Team Sync" tomorrow at 10 AM for 1 hour.

Search YouTube for recent videos about machine learning.

其他使用方式

在 Cloudflare AI Playground 中使用

你可以使用 Cloudflare AI Playground 在线测试 MCP 服务：

1. 打开 Cloudflare AI Playground
2. 输入 MCP 服务 URL，并添加 /sse 路径：

   https://your-project.your-username.workers.dev/sse
   

3. 通过 Playground 界面开始与 Google 服务交互

使用 MCP Inspector 离线测试

无需部署到 Cloudflare，即可进行本地开发和测试：

1. 在项目根目录中创建 .dev.vars 文件，并写入所需的环境变量：

   GOOGLE_OAUTH_CLIENT_ID="your-client-id"
   GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
   COOKIE_ENCRYPTION_KEY="your-random-encryption-key"
   

2. 使用 Bun：

   # Install dependencies
   bun install
   
   # Run local development server
   bun run dev
   

3. 使用 MCP Inspector 测试：

   bunx @modelcontextprotocol/inspector@latest
   

   这会启动本地界面，用于测试 MCP 服务的功能

OAuth 授权

首次通过 AI 客户端使用该服务时，你需要授权其访问 Google 账号：

1. 服务会显示授权对话框
2. 批准 MCP 客户端访问你的服务
3. 按照 Google OAuth 流程授予 API 访问权限
4. 授权完成后，你会被重定向回 AI 客户端

本地开发

如需在本地运行服务：

bun install
bun run dev

这将启动本地开发服务，通常位于 http://localhost:8788

故障排除

• OAuth 问题：确保 Google Cloud 项目设置了正确的重定向 URI
• API 权限：检查是否已在 Google Cloud Console 中启用所有必需的 API
• 令牌过期：如果遇到身份验证错误，请尝试清除 KV 存储并重新进行身份验证

感谢使用 Google MCP Remote！如有任何问题或建议，欢迎提交 issue 或为项目做出贡献。