mcp-gsuite MCP 服务器

用于与 Google 产品交互的 MCP 服务器。

示例提示

目前，此 MCP 服务器支持 Gmail 和日历集成，具有以下功能：

1. 通用

   • 多个 Google 帐户

2. Gmail

   • 获取您的 Gmail 用户信息
   • 使用灵活的搜索查询电子邮件（例如，未读、来自特定发件人、日期范围、带有附件）
   • 按 ID 检索完整的电子邮件内容
   • 创建包含收件人、主题、正文和抄送选项的新草稿电子邮件
   • 删除草稿电子邮件
   • 回复现有电子邮件（可以立即发送或保存为草稿）
   • 通过 ID 一次检索多封电子邮件。
   • 将电子邮件中的多个附件保存到您的本地系统。

3. 日历

   • 管理多个日历
   • 获取指定时间范围内的日历事件
   • 创建日历事件，包含：
     • 标题、开始/结束时间
     • 可选的位置和描述
     • 可选的参与者
     • 自定义时区支持
     • 通知首选项
   • 删除日历事件

您可以尝试的示例提示：

• 检索我最新的未读消息

• 搜索来自 Scrum Master 的电子邮件

• 检索来自会计的所有电子邮件

• 获取关于 ABC 的电子邮件并总结它

• 给 Alice 的上一封电子邮件写一个友好的回复并上传草稿。

• 回复 Bob 的电子邮件，附上感谢信。将其存储为草稿

• 我明天有什么安排？

• 查看我的私人帐户的家庭日历下周的安排

• 我需要与 Tim 计划一个下周 2 小时的活动。推荐一些时间段。

快速开始

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 mcp-gsuite：

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

Oauth 2

Google Workspace (G Suite) API 需要 OAuth2 授权。请按照以下步骤设置身份验证：

1. 创建 OAuth2 凭据：

   • 转到 Google Cloud Console
   • 创建一个新项目或选择一个现有项目
   • 为您的项目启用 Gmail API 和 Google Calendar API
   • 转到“凭据”→“创建凭据”→“OAuth 客户端 ID”
   • 选择“桌面应用”或“Web 应用程序”作为应用程序类型
   • 使用所需信息配置 OAuth 同意屏幕
   • 添加授权的重定向 URI（包括 http://localhost:4100/code 用于本地开发）

2. 所需的 OAuth2 范围：

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

3. 然后在您的工作目录中创建一个 .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"
    }
}

4. 创建一个包含帐户信息的 .accounts.json 文件

{
    "accounts": [
        {
            "email": "alice@bob.com",
            "account_type": "personal",
            "extra_info": "Additional info that you want to tell Claude: E.g. 'Contains Family Calendar'"
        }
    ]
}

您可以指定多个帐户。确保它们在您的 Google Auth 应用程序中具有访问权限。extra_info 字段特别有趣，因为您可以在此处添加您想告诉 AI 关于该帐户的信息（例如，它是否具有特定的议程）

注意：当您第一次为特定帐户执行其中一个工具时，将打开一个浏览器，将您重定向到 Google 并要求您提供凭据、范围等。成功登录后，它会将凭据存储在名为 .oauth.{email}.json 的本地文件中。获得授权后，将使用刷新令牌。

Claude Desktop

在 MacOS 上：~/Library/Application\ Support/Claude/claude_desktop_config.json

在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

<details> <summary>开发/未发布的服务器配置</summary>

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-gsuite",
        "run",
        "mcp-gsuite"
      ]
    }
  }
}

注意：您还可以使用 uv run mcp-gsuite --accounts-file /path/to/custom/.accounts.json 来指定不同的帐户文件，或使用 --credentials-dir /path/to/custom/credentials 来指定不同的凭据目录。

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-gsuite",
        "run",
        "mcp-gsuite",
        "--accounts-file",
        "/path/to/custom/.accounts.json",
        "--credentials-dir",
        "/path/to/custom/credentials"
      ]
    }
  }
}

</details>

<details> <summary>已发布的服务器配置</summary>

{
  "mcpServers": {
    "mcp-gsuite": {
      "command": "uvx",
      "args": [
        "mcp-gsuite",
        "--accounts-file",
        "/path/to/custom/.accounts.json",
        "--credentials-dir",
        "/path/to/custom/credentials"
      ]
    }
  }
}

</details>

配置选项

可以使用多个命令行选项配置 MCP 服务器，以指定身份验证和帐户信息的自定义路径：

• --gauth-file：指定包含 OAuth2 客户端配置的 .gauth.json 文件的路径。默认为 ./.gauth.json。
• --accounts-file：指定包含有关 Google 帐户信息的 .accounts.json 文件的路径。默认为 ./.accounts.json。
• --credentials-dir：指定成功身份验证后存储 OAuth 凭据的目录。默认为当前工作目录，每个帐户都有一个子目录，格式为 .oauth.{email}.json。

这些选项允许灵活地管理不同的环境或多组凭据和帐户，这在开发和测试场景中尤其有用。

用法示例：

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

当您运行具有不同配置的服务器的多个实例，或者部署到不适合默认路径的环境时，此配置特别有用。

开发

构建和发布

要准备用于分发的软件包：

1. 同步依赖项并更新锁定文件：

uv sync

2. 构建软件包分发：

uv build

这将在 dist/ 目录中创建源和 wheel 分发。

3. 发布到 PyPI：

uv publish

注意：您需要通过环境变量或命令标志设置 PyPI 凭据：

• 令牌：--token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于 MCP 服务器通过 stdio 运行，因此调试可能具有挑战性。为了获得最佳的调试体验，我们强烈建议使用 MCP Inspector。

您可以使用此命令通过 npm 启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-gsuite run mcp-gsuite

启动后，Inspector 将显示一个 URL，您可以在浏览器中访问该 URL 以开始调试。

您还可以使用以下命令查看服务器日志：

tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-gsuite.log