使用说明

项目简介

mcp-gsuite 是一个基于 Model Context Protocol (MCP) 构建的服务器，它充当 LLM 客户端（如 Claude Desktop）与 Google Workspace (G Suite) 产品之间的桥梁。通过 mcp-gsuite，LLM 客户端可以安全、可扩展地访问和操作用户的 Gmail 和 Calendar 数据，实现更智能的应用集成。

主要功能点

通用功能:
- 支持多 Google 账户：允许用户配置和使用多个 Google 账户。
Gmail 集成:
- 获取用户信息：检索已授权 Gmail 账户的用户信息。
- 灵活查询邮件：根据关键词、发送者、日期范围、附件等条件搜索邮件。
- 获取邮件内容：通过邮件 ID 获取完整的邮件内容。
- 创建草稿邮件：创建新的草稿邮件，支持收件人、主题、正文和抄送。
- 删除草稿邮件：删除指定的草稿邮件。
- 回复邮件：回复现有邮件，可以选择立即发送或保存为草稿。
- 批量操作邮件：一次性检索多个邮件或保存多个附件。
Calendar 集成:
- 管理多个日历：支持管理和访问用户的多个日历。
- 查询日历事件：在指定时间范围内检索日历事件。
- 创建日历事件：创建新的日历事件，支持标题、时间、地点、描述、参与者、时区和通知设置。
- 删除日历事件：删除指定的日历事件。

安装步骤

安装 mcp-gsuite

您可以通过 Smithery 客户端或手动安装 mcp-gsuite。

通过 Smithery 客户端安装 (推荐 Claude Desktop 用户):

打开终端并运行以下命令，将 mcp-gsuite 安装到 Claude Desktop 客户端：
```
npx -y @smithery/cli install mcp-gsuite --client claude
```
手动安装:

请参考仓库 README.md 文档中的 "Quickstart" -> "Install" 部分，根据您的环境进行手动安装。

配置 OAuth 2.0 授权

mcp-gsuite 需要通过 OAuth 2.0 授权才能访问您的 Google Workspace 数据。请按照以下步骤配置授权：

a. 创建 OAuth 2.0 凭据:

访问 Google Cloud Console。
创建或选择一个现有项目。
为您的项目启用 Gmail API 和 Google Calendar API。
转到 "凭据" -> "创建凭据" -> "OAuth 客户端 ID"。
选择 "桌面应用" 或 "Web 应用程序" 作为应用程序类型。
配置 OAuth 同意屏幕，填写必要信息。
添加授权重定向 URI，例如 'http://localhost:4100/code' (用于本地开发)。

b. 设置 OAuth 2.0 作用域:

确保您的 OAuth 2.0 应用配置了以下作用域：

[
  "openid",
  "https://mail.google.com/",
  "https://www.googleapis.com/auth/calendar",
  "https://www.googleapis.com/auth/userinfo.email"
]

c. 创建 '.gauth.json' 文件:

在您的工作目录（例如 mcp-gsuite 仓库根目录）下创建 '.gauth.json' 文件，并填入您的 OAuth 2.0 客户端 ID 和客户端密钥：

{
    "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"
    }
}

请替换 '$your_client_id' 和 '$your_client_secret' 为您在 Google Cloud Console 中创建的凭据。

d. 创建 '.accounts.json' 文件:

在您的工作目录（例如 mcp-gsuite 仓库根目录）下创建 '.accounts.json' 文件，并填入您的 Google 账户信息：

{
    "accounts": [
        {
            "email": "[email protected]",
            "account_type": "personal",
            "extra_info": "例如: 包含家庭日历"
        }
    ]
}

请替换 '[email protected]' 为您要使用的 Google 账户邮箱。'extra_info' 字段可以添加账户的额外信息，例如账户类型或包含的日历信息，这些信息可以帮助 LLM 更好地理解账户的用途。您可以配置多个账户。

运行 MCP 服务器

根据您的安装方式，运行 mcp-gsuite MCP 服务器。

如果通过 Smithery 安装，服务器通常会自动启动。 如果手动安装，请参考仓库 README.md 文档中的 "Quickstart" -> "Development/Unpublished Servers Configuration" 或 "Published Servers Configuration" 部分，根据您的需求选择合适的启动命令。

服务器配置 (MCP 客户端配置)

以下是 Claude Desktop 等 MCP 客户端配置 mcp-gsuite 服务器的示例 JSON 配置信息。您需要将此配置添加到您的 MCP 客户端配置文件中。

Claude Desktop 客户端配置示例 (Development/Unpublished Servers Configuration):

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",  // 启动命令，这里使用 uv (uvicorn 的别名)
      "args": [         // 启动参数
        "--directory",  // 指定工作目录
        "<mcp-gsuite 仓库路径>", //  **请替换为您的 mcp-gsuite 仓库在您电脑上的实际路径**
        "run",          //  uv 命令的子命令，表示运行 Python 模块
        "mcp-gsuite"   //  要运行的 Python 模块名称 (mcp_gsuite.server:main)
      ]
    }
  }
}

请将 '<mcp-gsuite 仓库路径>' 替换为您电脑上 mcp-gsuite 仓库的实际路径。 例如，如果您的仓库位于 '~/Documents/mcp-gsuite'，则应替换为 '~/Documents/mcp-gsuite'。

注意： 如果您使用 "Published Servers Configuration"，请参考仓库 README.md 文档进行配置。

基本使用方法

启动 MCP 客户端 (如 Claude Desktop)。
在 MCP 客户端中配置并启用 mcp-gsuite 服务器。 确保您已按照 "服务器配置" 部分正确配置了服务器启动命令和参数。
在 LLM 对话中使用工具。 您可以使用自然语言指令，指示 LLM 客户端调用 mcp-gsuite 提供的工具来操作 Gmail 或 Calendar。

例如，在 Claude Desktop 中，您可以尝试以下指令：
- "Retrieve my latest unread messages" (检索我最新的未读邮件)
- "What do I have on my agenda tomorrow?" (我明天有什么日程安排？)
- "Create a calendar event for meeting with Tim next week for 2 hours." (下周安排一个和 Tim 开会的日历事件，时长 2 小时。)
更多示例指令，请参考仓库 README.md 文档中的 "Example prompts" 部分。

首次使用工具时，mcp-gsuite 服务器可能会启动浏览器进行 OAuth 2.0 授权。请按照提示完成授权流程。授权成功后，凭据将被保存，后续使用将无需重复授权。

关键词