关键词

Gmail集成Calendar集成邮件管理日程管理Google Workspace

G Suite Integration MCP Server 使用说明

项目简介

G Suite Integration MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在为大型语言模型 (LLM) 客户端提供与 Google Workspace (G Suite) 产品（目前主要支持 Gmail 和 Calendar）集成的能力。通过此 MCP Server，LLM 可以安全、可控地访问用户的 Gmail 邮箱和 Google 日历，执行如邮件查询、邮件草稿创建、日历事件管理等操作，从而扩展 LLM 的应用场景和功能边界。

主要功能点

  • Gmail 集成:
    • 查询邮件：支持灵活的邮件搜索条件（如未读邮件、特定发件人、日期范围、带附件等）。
    • 获取邮件内容：根据邮件 ID 获取完整的邮件内容，包括正文和附件信息。
    • 创建邮件草稿：创建新的邮件草稿，可指定收件人、主题、正文和抄送人。
    • 删除邮件草稿：根据邮件 ID 删除指定的邮件草稿。
    • 回复邮件：回复现有邮件，可以选择立即发送或保存为草稿。
    • 获取邮件附件：下载邮件附件到本地系统或作为资源返回。
    • 批量操作：支持批量获取邮件和批量保存附件。
  • Calendar 集成:
    • 管理多个日历：支持管理和访问用户关联的多个 Google 日历。
    • 获取日历事件：查询指定时间范围内的日历事件。
    • 创建日历事件：创建新的日历事件，可设置标题、开始/结束时间、地点、描述、参与者、时区和通知偏好。
    • 删除日历事件：根据事件 ID 删除指定的日历事件。
  • 多 Google 账户支持: 支持配置和使用多个 Google 账户。
  • OAuth 2.0 授权: 采用 OAuth 2.0 协议进行安全授权，保障用户数据安全。

安装步骤

  1. 安装 Smithery CLI (如果使用 Smithery 安装): 如果您使用 Smithery 客户端 (如 Claude Desktop)，可以通过 Smithery CLI 快速安装。如果手动配置，请跳过此步骤。

    npm install -g @smithery/cli

  2. 通过 Smithery 安装 (可选): 如果您使用 Claude Desktop 等 Smithery 客户端，可以使用以下命令自动安装 G Suite Integration MCP Server：

    npx -y @smithery/cli install @alBERT-launcher/mcp-gsuite --client claude

  3. 手动安装 (如果未使用 Smithery):

    • 确保您的系统已安装 Python 和 uv (建议使用 uv 进行包管理，参考仓库 README)。
    • 克隆或下载此 GitHub 仓库的代码。
    • 在仓库根目录下，使用 uv 安装项目依赖： 
      uv sync
    • 构建项目 (可选，如果需要发布到 PyPI)： 
      uv build

  4. 配置 OAuth 2.0 授权:

    • 前往 Google Cloud Console 创建或选择现有项目。
    • 启用 Gmail API 和 Google Calendar API。
    • 创建 OAuth 客户端 ID：选择“桌面应用”或“Web 应用程序”类型，配置 OAuth 同意屏幕，并添加授权重定向 URI 'http://localhost:4100/code' (用于本地开发)。
    • 将生成的客户端 ID 和客户端密钥填入仓库根目录下的 '.gauth.json' 文件 (如果文件不存在则手动创建)，示例如下: 
      {
    "web": {
        "client_id": "$your_client_id",
        "client_secret": "$your_client_secret",
        "redirect_uris": ["http://localhost:4100/code"],
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token"
    }
}
    • 创建 '.accounts.json' 文件 (如果文件不存在则手动创建)，配置您希望 LLM 访问的 Google 账户信息，示例如下： 
      {
    "accounts": [
        {
            "email": "[email protected]",
            "account_type": "personal",
            "extra_info": "可选的账户额外信息，例如 'Contains Family Calendar'"
        }
    ]
}
      可以配置多个账户。'extra_info' 字段可以用来描述账户的用途或特点，供 LLM 参考。

服务器配置

MCP 客户端 (例如 Claude Desktop) 需要配置 MCP 服务器的启动命令才能连接和使用 G Suite Integration MCP Server。以下是针对不同情况的配置示例，请根据您的实际部署情况选择合适的配置，并将其添加到 MCP 客户端的配置文件中 (例如 Claude Desktop 的 'claude_desktop_config.json')。

开发/未发布服务器配置 (使用 'uv run' 启动): 适用于开发环境，服务器代码位于本地仓库目录中。

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-gsuite",  // 请替换为您的 mcp-gsuite 仓库的绝对路径
        "run",
        "mcp-gsuite"
      ]
    }
  }
}

已发布服务器配置 (假设已使用 'uvx' 打包和发布): 适用于已打包发布的环境，假设 'mcp-gsuite' 可执行文件已在系统 PATH 中。

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uvx",
      "args": [
        "mcp-gsuite"
      ]
    }
  }
}

自定义配置参数: 您可以使用以下命令行参数自定义服务器配置，例如指定 '.gauth.json'、'.accounts.json' 和 OAuth 凭据存储目录的路径：

uv run mcp-gsuite --gauth-file /path/to/custom/.gauth.json --accounts-file /path/to/custom/.accounts.json --credentials-dir /path/to/custom/credentials

在 MCP 客户端的 'args' 数组中添加相应的参数即可。

基本使用方法

  1. 启动 MCP 服务器: 根据您选择的配置方式，运行相应的命令启动 MCP 服务器。例如，在仓库根目录下执行 'uv run mcp-gsuite'。
  2. 配置 MCP 客户端: 将上述 “服务器配置” 部分提供的 JSON 配置添加到您的 MCP 客户端配置文件中，并确保 'command' 和 'args' 配置正确。
  3. 在 LLM 中使用工具: 在支持 MCP 协议的 LLM 应用中，您应该能够发现并调用 G Suite Integration MCP Server 提供的工具。例如，您可以指示 LLM 查询 Gmail 邮件、创建日历事件等。首次使用需要授权 Google 账户，按照提示完成 OAuth 授权流程即可。

首次授权流程: 当 LLM 首次调用需要访问 Google 账户的工具时，服务器会自动启动 OAuth 授权流程：

  • 服务器会在本地启动一个 HTTP 服务器监听 'http://localhost:4100/code'。
  • 服务器会尝试自动打开您的默认浏览器，并跳转到 Google 授权页面。如果未能自动打开，请手动复制授权 URL 在浏览器中打开。
  • 在 Google 授权页面，选择您要授权的 Google 账户，并授予 G Suite Integration MCP Server 相应的权限（Gmail 和 Calendar）。
  • 授权成功后，浏览器会跳转到 'http://localhost:4100/code?code=...'，显示 "Auth successful! You can close the tab!"。此时您可以关闭该页面。
  • 授权凭据 (refresh token) 会被安全地存储在本地，后续使用将自动刷新 access token，无需再次手动授权。

调试

可以使用 MCP Inspector 工具进行调试，详细步骤请参考仓库 README。

请注意，首次使用 Gmail 或 Calendar 工具时，需要进行 OAuth 2.0 授权。请确保按照步骤正确配置 OAuth 客户端 ID 和密钥，并授权您的 Google 账户。

信息

分类

生产力应用

访问项目