MCP Google Workspace 服务器

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

特征

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

Related MCP server: Gmail MCP Server

示例提示

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

Gmail

“检索我最近的未读消息”
“搜索来自 Scrum Master 的我的邮件”
“从会计部门检索所有电子邮件”
“拿关于 ABC 的电子邮件来总结一下”
“给 Alice 的上一封电子邮件写一封友好的回复并上传草稿”
“回复Bob的邮件并附上感谢信。请将其保存为草稿。”

日历

“我明天有什么安排？”
“查看我的私人账户下周的家庭日程”
我需要和 Tim 一起计划下周一个 2 小时的活动。请提供一些时间段供您参考。

先决条件

Node.js >= 18
启用了 Gmail 和日历 API 的 Google Cloud 项目
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”
- 选择“桌面应用程序”或“Web应用程序”作为应用程序类型
- 使用所需信息配置 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"
]

使用您的 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"]
  }
}

创建一个.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"
      ]
    }
  }
}

用法

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

可用工具

账户管理

gmail_list_accounts / calendar_list_accounts
- 列出所有已配置的 Google 帐户
- 查看帐户元数据和说明
- 不需要 user_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
- 在单个请求中按 ID 检索多个电子邮件
- 高效批处理
gmail_create_draft
- 创建新的电子邮件草稿
- 支持抄送收件人
gmail_delete_draft
- 根据 ID 删除电子邮件草稿
gmail_reply
- 回复现有电子邮件
- 选择立即发送或保存为草稿
- 支持通过抄送“回复全部”
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           # 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 ：以自动重新加载的方式启动开发模式

贡献

分叉存储库
创建功能分支
提交你的更改
推送到分支
创建拉取请求

执照

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

MCP Google Workspace Server