MCP Google Workspace 服务器

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

功能

• 多 Google 账户支持

  • 使用和切换多个 Google 账户
  • 每个账户可以有自定义元数据和描述

• Gmail 集成

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

• 日历集成

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

示例提示

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

Gmail

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

日历

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

前提条件

• Node.js >= 18
• 一个启用了 Gmail 和 Calendar API 的 Google Cloud 项目
• 用于 Google API 的 OAuth 2.0 凭证

安装

1. 克隆仓库：
   bash
   git clone https://github.com/j3k0/mcp-google-workspace.git
   cd mcp-google-workspace

2. 安装依赖项：
   bash
   npm install

3. 构建 TypeScript 代码：
   bash
   npm run build

配置

OAuth 2.0 设置

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

1. 创建 OAuth2 凭证：

   • 访问 Google Cloud 控制台
   • 创建一个新项目或选择现有项目
   • 为您的项目启用 Gmail API 和 Google 日历 API
   • 转到“凭据”→“创建凭据”→“OAuth 客户端 ID”
   • 选择“桌面应用”或“Web 应用程序”作为应用程序类型
   • 配置 OAuth 同意屏幕，填写所需信息
   • 添加授权重定向 URI（包括 http://localhost:4100/code 用于本地开发）

2. 所需的 OAuth2 范围：
   json
   [
   "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 凭证：
   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 账户可以使用该服务器：
   json
   {
   "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

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

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

使用方法

1. 启动服务器：
   bash
   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

   • 通过单个请求获取多个邮件
   • 适用于批量处理

4. gmail_create_draft

   • 创建新的邮件草稿
   • 支持 CC 收件人

5. gmail_delete_draft

   • 通过 ID 删除邮件草稿

6. gmail_reply

   • 回复现有邮件
   • 选项包括立即发送或保存为草稿
   • 通过 CC 支持“回复全部”

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 文件