Google Workspace MCP Server

关键词

Google Drive 集成OAuth 授权LLM 上下文服务工具注册与执行Prompts 渲染

使用说明

  • 项目简介
    • 这是一个完整的 MCP 服务器实现，能够托管 Google Drive、Docs、Sheets、Slides、Calendar、Gmail、Contacts 等服务的资源、工具和 Prompt 模板，并通过 MCP 的 JSON-RPC 接口与 LLM 客户端进行交互。服务器端负责认证、会话管理、工具注册与执行、Prompt 渲染，以及对请求的统一错误处理与日志输出。
  • 主要功能点
    • 资源管理：对 Google Drive 等服务的资源进行列举、读取、获取元数据等操作的后端实现。
    • 工具注册与执行：将 Drive、Docs、Sheets、Slides、Calendar、Gmail、Contacts 等服务的工具暴露给 LLM 客户端，支持统一的错误处理与重试机制。
    • Prompt 定义与渲染：提供 Prompts 的定义与消息生成，支持 LLM 与人机交互的模板化对话。
    • JSON-RPC 通信：遵循 MCP 服务器的请求/响应模式，通过标准的 JSON-RPC 与客户端通信。
    • 会话与鉴权：内置 OAuth2 流程、令牌持久化、令牌刷新与令牌错误处理，支持多账户/多配置的场景。
    • 安全与扩展性：使用 PKCE、循环日志输出、错误映射与可观测性工具，便于集成与扩展。
    • 多传输协议支持：底层传输适配设计，便于未来扩展（如 Stdio、SSE、WebSocket 等）。
  • 安装与运行
    1. 依赖与构建
      • 安装 Node.js 22+，并在项目根目录执行 npm install。
      • 运行构建：执行 npm run build（会把 TypeScript 代码打包为 dist/index.js）。
    2. 认证配置
      • 需要 Google Cloud Project，启用 Drive、Docs、Sheets、Slides、Calendar、Gmail、People 等 API。
      • 按 README 指引把 OAuth 客户端凭据保存到默认位置或配置环境变量（GOOGLE_DRIVE_OAUTH_CREDENTIALS、GOOGLE_WORKSPACE_MCP_TOKEN_PATH、GOOGLE_WORKSPACE_MCP_PROFILE 等）。
      • 通过命令 npx @dguido/google-workspace-mcp auth 启动并完成 OAuth 授权，令牌将被持久化。
    3. 启动 MCP 服务器
      • 使用 npx 启动服务器，或直接运行打包后的可执行入口 dist/index.js。
      • 启动后，服务器会输出版本、进程信息等日志，便于排错和监控。
    4. 配置客户端对接
      • MCP 客户端（如 Claude Desktop）需要配置一个或多个 MCP 服务器入口，客户端通常只需要知道服务器名称、启动命令和参数即可建立连接。
      • Quick Start 中的 Claude Desktop 配置示例给出现代化的 JSON 配置：通过 npx 启动服务器，环境变量可控制启用的服务集合（drive,gmail,calendar 等）。
  • 服务器配置（示例，供参考，不用于直接执行代码）
    • 服务器端名称：google-workspace-mcp
    • 启动命令与参数（示例）：
      • 命令: npx
      • 参数: ["@dguido/google-workspace-mcp"]
      • 环境变量示例（可选）:
        • GOOGLE_WORKSPACE_SERVICES: "drive,gmail,calendar" // 启用的服务集合
        • 其他可选变量如 GOOGLE_DRIVE_OAUTH_CREDENTIALS、GOOGLE_WORKSPACE_MCP_TOKEN_PATH、GOOGLE_WORKSPACE_MCP_PROFILE 等按需配置
    • 配置文件示例（JSON，供客户端读取并连接）：
      • serverName: "google-workspace-mcp"
      • command: "npx"
      • args: ["@dguido/google-workspace-mcp"]
      • env: { "GOOGLE_WORKSPACE_SERVICES": "drive,gmail,calendar" }
  • 基本使用方法
    • 认证后配置客户端
      • 在 Claude Desktop（或其他 MCP 客户端）中添加一个 MCP 服务器，服务器名称填为 google-workspace-mcp，命令填为 npx，参数填为 ["@dguido/google-workspace-mcp"]，环境变量按需要设置。
    • 使用场景
      • 通过 MCP 客户端请求资源（如读取 Google Drive 文件、列出文件夹、读取 Docs/Sheets/Slides 内容）、调用工具（如搜索、创建文档、发送邮件等）、获取 Prompts（列出、获取提示详情）以及状态信息。
    • 典型流程
        1. 运行 npx @dguido/google-workspace-mcp auth 完成首次授权（后续自动使用存储的 tokens）。
        1. 启动 MCP 服务器（npx @dguido/google-workspace-mcp start）。
        1. 在 LLM 客户端中发起资源读取、工具调用或 Prompt 获取等请求，服务器按 MCP 协议返回 JSON-RPC 响应。
  • 说明与注意
    • 该实现包含完整的服务端能力、错误映射、日志、和多工具联合使用能力，理论上可以直接用于生产环境，只要正确完成 Google API 的凭据配置与授权流程。
    • 如需扩展，遵循现有的工具注册和错误处理模式即可。

服务器信息

访问项目