MCP Google Workspace Server

MCP Google Workspace 服务器

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

特征

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

示例提示

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

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

用法

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'、'from: example@gmail.com '、'newer_than:2d'、'has'）
   • 按时间倒序返回电子邮件
   • 包括元数据和内容摘要
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 最佳实践

项目结构

开发命令

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

贡献

1. 分叉存储库
2. 创建功能分支
3. 提交你的更改
4. 推送到分支
5. 创建拉取请求

执照

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