mcp-gsuite MCP server

mcp-gsuite MCP 服务

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

示例提示词

目前，此 MCP 服务支持集成 Gmail 和 Calendar，并提供以下功能：

1. 通用

• 多个 Google 账号

2. Gmail

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

3. Calendar

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

可以尝试的示例提示词：

• 获取我最新的未读消息

• 搜索 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
   • 前往“Credentials” → “Create Credentials” → “OAuth client ID”
   • 选择“Desktop app”或“Web application”作为应用类型
   • 使用所需信息配置 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": "[email protected]",
            "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

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

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

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

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