谷歌工作空间MCP

Name: 谷歌工作空间MCP
Author: j3k0

作者：j3k017 星标更新：2025-04-01

安装使用来源：spider==github.com

项目介绍

MCP Google Workspace 服务器

这是一个用于 Google Workspace 服务的模型上下文协议（Model Context Protocol）服务器。该服务器提供了通过 MCP 协议与 Gmail 和 Google 日历进行交互的工具。

功能

支持多个 Google 账户
- 使用并切换多个 Google 账户
- 每个账户可以有自定义元数据和描述信息
Gmail 集成
- 使用高级搜索查询邮件
- 查看完整的邮件内容和附件
- 创建和管理草稿
- 回复邮件
- 归档邮件
- 处理附件
- 支持批量操作
日历集成
- 列出可用的日历
- 查看日历事件
- 创建新的事件
- 删除事件
- 支持多个日历
- 自定义时区支持

示例提示

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

Gmail

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

日历

“明天我的日程是什么？”
“检查我的私人账户下周的家庭日程”
“我需要在下周与Tim安排一个两小时的活动。建议一些时间槽”

先决条件

Node.js >= 18
启用了Gmail和日历API的Google云项目
Google API的OAuth 2.0凭证

安装

克隆仓库：

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

安装依赖项：
```
npm install
```
构建TypeScript代码：
```
npm run build
```

配置

OAuth 2.0 设置

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

创建OAuth2凭证：
- 访问Google Cloud Console
- 创建新项目或选择现有项目
- 为您的项目启用Gmail API和Google日历API
- 前往“凭证”→“创建凭证”→“OAuth客户端ID”
- 选择“桌面应用”或“网络应用”作为应用程序类型
- 使用所需信息配置OAuth同意屏幕
- 添加授权重定向URI（包括http://localhost:4100/code用于本地开发）

必需的OAuth2范围：

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

在项目根目录中创建一个.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"]
  }
}

创建一个.accounts.json文件以指定哪些Google账户可以使用该服务器：
```
{
  "accounts": [
    {
      "email": "your.email@gmail.com",
      "account_type": "personal",
      "extra_info": "主要账户，带有家庭日历"
    }
  ]
}
```
您可以指定多个账户。确保它们在您的Google认证应用中有访问权限。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>

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

</details>

使用方法

启动服务器：
```
npm start
```
可选参数：
- --gauth-file：OAuth2凭证文件路径（默认：./.gauth.json）
- --accounts-file：账户配置文件路径（默认：./.accounts.json）
- --credentials-dir：存储OAuth凭证的目录（默认：当前目录）
服务器将启动并监听通过标准输入/输出的MCP命令。
对于每个账户的首次运行，它将：
- 打开浏览器窗口进行OAuth2身份验证
- 监听端口4100以接收OAuth2回调
- 将凭证存储在一个名为.oauth2.{email}.json的文件中，以便将来使用

可用工具

账户管理

gmail_list_accounts / calendar_list_accounts
- 列出所有配置的Google账户
- 查看账户元数据和描述信息
- 不需要用户ID

Gmail 工具

gmail_query_emails
- 使用Gmail查询语法搜索邮件（例如，'is:unread'，'from:example@gmail.com'，'newer_than:2d'，'has:attachment'）
- 返回按逆时间顺序排列的邮件
- 包括元数据和内容摘要
gmail_get_email
- 根据ID检索完整的邮件内容
- 包括完整的消息正文和附件信息
gmail_bulk_get_emails
- 在单个请求中检索多个邮件
- 适用于批处理处理
gmail_create_draft
- 创建新的邮件草稿
- 支持CC收件人
gmail_delete_draft
- 根据ID删除草稿邮件
gmail_reply
- 回复现有邮件
- 选项立即发送或保存为草稿
- 支持通过CC进行“全部回复”
gmail_get_attachment
- 下载邮件附件
- 保存到磁盘或返回为嵌入资源
gmail_bulk_save_attachments
- 在单个操作中保存多个附件
gmail_archive / gmail_bulk_archive
- 将邮件移出收件箱
- 支持单独或批量操作

日历工具

calendar_list
- 列出所有可访问的日历
- 包括日历元数据、访问角色和时区信息
calendar_get_events
- 在日期范围内检索事件
- 支持多个日历
- 过滤选项（已删除事件、最大结果数）
- 时区定制
calendar_create_event
- 创建新的日历事件
- 支持参与者和通知
- 地点和描述字段
- 时区处理
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：以开发模式启动，自动重新加载

贡献

分叉仓库
创建功能分支
提交更改
推送到分支
创建拉取请求

许可证

MIT许可证 - 详情见LICENSE文件