MCP Google Workspace 服务器

适用于 Google Workspace 服务的模型上下文协议 (MCP) 服务器。该服务器提供通过 MCP 协议与 Gmail 和 Google 日历交互的工具。

特征

• 支持多个 Google 帐户

  • 使用和切换多个 Google 帐户

  • 每个帐户可以有自定义元数据和描述

• Gmail 集成

  • 使用高级搜索查询电子邮件

  • 阅读完整的电子邮件内容和附件

  • 创建和管理草稿

  • 回复电子邮件

  • 存档电子邮件

  • 处理附件

  • 批量操作支持

• 日历集成

  • 列出可用的日历

  • 查看日历事件

  • 创建新事件

  • 删除事件

  • 支持多种日历

  • 自定义时区支持

Related MCP server: mcp-gsuite

示例提示

使用你的人工智能助手尝试以下示例提示：

Gmail

• “检索我最近的未读消息”

• “搜索来自 Scrum Master 的我的邮件”

• “从会计部门检索所有电子邮件”

• “拿关于 ABC 的电子邮件来总结一下”

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

• “回复Bob的邮件并附上感谢信。请将其保存为草稿。”

日历

• “我明天有什么安排？”

• “查看我的私人账户下周的家庭日程”

• 我需要和 Tim 一起计划下周一个 2 小时的活动。请提供一些时间段供您参考。

先决条件

• Node.js >= 18

• 启用了 Gmail 和日历 API 的 Google Cloud 项目

• Google API 的 OAuth 2.0 凭据

安装

1. 克隆存储库：

   git clone https://github.com/j3k0/mcp-google-workspace.git
   cd mcp-google-workspace

2. 安装依赖项：

   npm install

3. 构建 TypeScript 代码：

   npm run build

配置

OAuth 2.0 设置

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

1. 创建 OAuth2 凭证：

   • 前往Google Cloud Console

   • 创建新项目或选择现有项目

   • 为您的项目启用 Gmail API 和 Google 日历 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. 使用您的 Google OAuth 2.0 凭据在项目根目录中创建一个.gauth.json文件：

   {
     "installed": {
       "client_id": "your_client_id",
       "project_id": "your_project_id",
       "auth_uri": "https://accounts.google.com/o/oauth2/auth",
       "token_uri": "https://oauth2.googleapis.com/token",
       "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
       "client_secret": "your_client_secret",
       "redirect_uris": ["http://localhost:4100/code"]
     }
   }

4. 创建一个.accounts.json文件来指定哪些 Google 帐户可以使用该服务器：

   {
     "accounts": [
       {
         "email": "your.email@gmail.com",
         "account_type": "personal",
         "extra_info": "Primary account with Family Calendar"
       }
     ]
   }

   您可以指定多个帐户。请确保这些帐户在您的 Google Auth 应用中具有访问权限。extra_info extra_info非常有用，因为您可以在此处添加想要告知 AI 的帐户信息（例如，该帐户是否有特定的日历）。

Claude桌面配置

配置 Claude Desktop 以使用 mcp-google-workspace 服务器：

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

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

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "<dir_to>/mcp-google-workspace/launch"
    }
  }
}

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "npx",
      "args": [
        "mcp-google-workspace"
      ]
    }
  }
}

用法

1. 启动服务器：

   npm start

   可选参数：

   • --gauth-file ：OAuth2 凭证文件的路径（默认值：./.gauth.json）

   • --accounts-file ：帐户配置文件的路径（默认值：./.accounts.json）

   • --credentials-dir ：存储 OAuth 凭证的目录（默认值：当前目录）

2. 服务器将启动并通过 stdin/stdout 监听 MCP 命令。

3. 每个帐户首次运行时，它将：

   • 打开浏览器窗口进行 OAuth2 身份验证

   • 在端口 4100 上监听 OAuth2 回调

   • 将凭证存储在名为.oauth2.{email}.json的文件中以供将来使用

可用工具

账户管理

1. gmail_list_accounts / calendar_list_accounts

   • 列出所有已配置的 Google 帐户

   • 查看帐户元数据和说明

   • 不需要 user_id

Gmail 工具

1. gmail_query_emails

   • 使用 Gmail 的查询语法搜索电子邮件（例如，'is:unread'、'from: example@gmail.com '、'newer_than:2d'、'has:attachment'）

   • 按时间倒序返回电子邮件

   • 包括元数据和内容摘要

2. gmail_get_email

   • 通过 ID 检索完整的电子邮件内容

   • 包含完整的邮件正文和附件信息

3. gmail_bulk_get_emails

   • 在单个请求中按 ID 检索多个电子邮件

   • 高效批处理

4. gmail_create_draft

   • 创建新的电子邮件草稿

   • 支持抄送收件人

5. gmail_delete_draft

   • 根据 ID 删除电子邮件草稿

6. gmail_reply

   • 回复现有电子邮件

   • 选择立即发送或保存为草稿

   • 支持通过抄送“回复全部”

7. gmail_get_attachment

   • 下载电子邮件附件

   • 保存到磁盘或作为嵌入资源返回

8. gmail_bulk_save_attachments

   • 一次操作即可保存多个附件

9. gmail_archive / gmail_bulk_archive

   • 将电子邮件移出收件箱

   • 支持单个或批量操作

日历工具

1. calendar_list

   • 列出所有可访问的日历

   • 包括日历元数据、访问角色和时区信息

2. calendar_get_events

   • 检索某个日期范围内的事件

   • 支持多种日历

   • 过滤选项（已删除事件、最大结果）

   • 时区定制

3. calendar_create_event

   • 创建新的日历事件

   • 支持与会者和通知

   • 位置和描述字段

   • 时区处理

4. calendar_delete_event

   • 按 ID 删除事件

   • 取消通知选项

发展

• 源代码位于src/目录下的 TypeScript 中

• 构建输出进入dist/目录

• 使用 ES 模块实现更好的模块化

• 遵循 Google API 最佳实践

项目结构

mcp-google-workspace/
├── src/
│   ├── server.ts           # Main server implementation
│   ├── services/
│   │   └── gauth.ts        # Google authentication service
│   ├── tools/
│   │   ├── gmail.ts        # Gmail tools implementation
│   │   └── calendar.ts     # Calendar tools implementation
│   └── types/
│       └── tool-handler.ts # Common types and interfaces
├── .gauth.json             # OAuth2 credentials
├── .accounts.json          # Account configuration
├── package.json            # Project dependencies
└── tsconfig.json           # TypeScript configuration

开发命令

• npm run build ：构建 TypeScript 代码

• npm start ：启动服务器

• npm run dev ：以自动重新加载的方式启动开发模式

贡献

1. 分叉存储库

2. 创建功能分支

3. 提交你的更改

4. 推送到分支

5. 创建拉取请求

执照

MIT 许可证 - 详情请参阅许可证文件