MCP Google Workspace 服务器

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

功能

• 多 Google 账号支持

  • 使用并在多个 Google 账号之间切换
  • 每个账号都可以有自定义的元数据和描述

• Gmail 集成

  • 使用高级搜索查询电子邮件
  • 读取完整的电子邮件内容和附件
  • 创建和管理草稿
  • 回复电子邮件
  • 存档电子邮件
  • 处理附件
  • 支持批量操作

• 日历集成

  • 列出可用的日历
  • 查看日历事件
  • 创建新事件
  • 删除事件
  • 支持多个日历
  • 自定义时区支持

示例提示

尝试使用以下示例提示与您的 AI 助手：

Gmail

• "检索我最新的未读消息"
• "搜索来自 Scrum Master 的电子邮件"
• "检索来自会计的所有电子邮件"
• "获取关于 ABC 的电子邮件并总结它"
• "写一封友好的回复给 Alice 的最后一封电子邮件并上传草稿"
• "回复 Bob 的电子邮件，附上感谢信。将其存储为草稿"

日历

• "我明天有什么安排？"
• "查看我的私人帐户的家庭日历下周的安排"
• "我需要与 Tim 计划一个为期 2 小时的活动，下周。建议一些时间段"

前提条件

• Node.js >= 18
• 启用了 Gmail 和 Calendar 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 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 文件，其中包含您的 Google OAuth 2.0 凭据：

   {
     "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 字段特别有用，因为您可以在此处添加您想告诉 AI 关于该帐户的信息（例如，它是否具有特定的日历）。

Claude Desktop 配置

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

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

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

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

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

</details>

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

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

</details>

用法

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           # 主要服务器实现
│   ├── services/
│   │   └── gauth.ts        # Google 身份验证服务
│   ├── tools/
│   │   ├── gmail.ts        # Gmail 工具实现
│   │   └── calendar.ts     # 日历工具实现
│   └── types/
│       └── tool-handler.ts # 通用类型和接口
├── .gauth.json             # OAuth2 凭据
├── .accounts.json          # 帐户配置
├── package.json            # 项目依赖项
└── tsconfig.json           # TypeScript 配置

开发命令

• npm run build: 构建 TypeScript 代码
• npm start: 启动服务器
• npm run dev: 以自动重新加载的开发模式启动

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到分支
5. 创建一个 Pull Request

许可证

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件