MCP Google Workspace Server

MCP Google Workspace 服务

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

功能

• 支持多个 Google 账号

  • 使用和切换多个 Google 账号
  • 每个账号均可设置自定义元数据和描述

• Gmail 集成

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

• Calendar 集成

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

示例提示词

尝试将这些示例提示词用于你的 AI 助手：

Gmail

• “检索我最新的未读邮件”
• “搜索 Scrum Master 发给我的邮件”
• “检索所有来自会计部门的邮件”
• “找到关于 ABC 的邮件并进行总结”
• “为 Alice 的上一封邮件撰写一封得体的回复，并保存为草稿”
• “回复 Bob 的邮件并表示感谢。将其保存为草稿”

Calendar

• “我明天的日程安排是什么？”
• “查看我私人账号下下周的家庭日程”
• “我需要和 Tim 计划下周的一场活动，时长 2 小时。请推荐一些时间段”

先决条件

• Node.js >= 20
• 已启用 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 控制台
   • 创建新项目或选择现有项目
   • 为项目启用 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/gmail.settings.basic",
     "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": "[email protected]",
         "account_type": "personal",
         "extra_info": "Primary account with Family Calendar"
       }
     ]
   }
   

   你可以指定多个账号。请确保这些账号已在你的 Google Auth 应用中获得访问权限。extra_info 字段尤其有用，你可以在其中添加希望告知 AI 的账号信息（例如，该账号是否有特定日历）。

身份验证

配置好 .gauth.json 和 .accounts.json 后，为你的账号进行身份验证：

npm run authenticate

这会为每个已配置的账号打开浏览器，以完成 OAuth 同意流程。脚本会为每个账号等待回调，最长 5 分钟。

# Authenticate a specific account
npm run authenticate -- [email protected]

# Force re-authentication (e.g. after OAuth scope changes)
npm run authenticate -- [email protected] --force

# Custom config paths (same flags as the server)
npm run authenticate -- --gauth-file /path/to/.gauth.json --accounts-file /path/to/.accounts.json

如果通过 npm 安装，也可以运行：

npx mcp-gmail-authenticate

Claude Desktop 配置

配置 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"
      ]
    }
  }
}

Docker

你也可以在 Docker 中构建并运行 MCP 服务：

docker build -t mcp-google-workspace .
docker run --rm -i \
  -v "$PWD/.gauth.json:/app/.gauth.json:ro" \
  -v "$PWD/.accounts.json:/app/.accounts.json:ro" \
  -v "$PWD/.credentials:/app/.credentials" \
  -e GMAIL_ALLOW_DRAFTS=true \
  -e GMAIL_ATTACHMENTS_DIR=/app/attachments \
  mcp-google-workspace \
  node dist/server.js --credentials-dir /app/.credentials

不要将 .gauth.json、.accounts.json、OAuth 令牌或 .env 文件打包到镜像中。随附的 .dockerignore 会排除这些文件；请在运行时挂载它们。

使用方法

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 的文件中，以供日后使用

环境变量

• GMAIL_ALLOW_SENDING — 设置为 true 以允许 gmail_send 实际发送邮件。默认禁用。
• GMAIL_ALLOW_DRAFTS — 设置为 true 以允许使用草稿创建工具。默认禁用。
• GMAIL_ATTACHMENTS_DIR — gmail_get_attachment 和 gmail_bulk_save_attachments 可在此基础目录下写入文件。调用方提供的附件路径将视为相对于此目录的路径；绝对路径、路径遍历以及逃逸出此目录的符号链接均会被拒绝。默认值为 ~/.mcp-gsuite/attachments。

可用工具

账户管理

1. gmail_list_accounts / calendar_list_accounts
   • 列出所有已配置的 Google 账户
   • 查看账户元数据和描述
   • 无需提供 user_id

Gmail 工具

1. gmail_query_emails

   • 使用 Gmail 查询语法搜索邮件（例如，'is:unread'、'from:[email protected]'、'newer_than:2d'、'has:attachment'）
   • 按时间倒序返回邮件
   • 包含元数据和内容摘要

2. gmail_get_email

   • 按 ID 获取完整邮件内容
   • 包含完整邮件正文和附件信息

3. gmail_bulk_get_emails

   • 在单次请求中按 ID 获取多封邮件
   • 适用于高效批量处理

4. gmail_create_draft

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

5. gmail_delete_draft

   • 按 draft_id 删除邮件草稿
   • 注意：draft_id 与 gmail_query_emails 返回的邮件 ID 不同。使用 gmail_list_drafts 获取该 ID。

6. gmail_list_drafts

   • 列出 Gmail 草稿，可选择使用 Gmail 搜索查询进行筛选
   • 返回每封草稿的 draft_id（gmail_delete_draft 所需）以及其 message_id、主题、收件人和摘要

7. gmail_reply

   • 回复现有邮件
   • 可选择立即发送或保存为草稿
   • 支持通过抄送实现“回复所有人”

8. gmail_get_attachment

   • 下载邮件附件
   • 保存到磁盘或作为嵌入式资源返回

9. gmail_bulk_save_attachments

   • 在单次操作中保存多个附件

10. gmail_archive / gmail_bulk_archive

    • 将邮件移出收件箱
    • 支持单封或批量操作

日历工具

1. calendar_list

   • 列出所有可访问的日历
   • 包含日历元数据、访问角色和时区信息

2. calendar_get_events

   • 获取指定日期范围内的活动
   • 支持多个日历
   • 可选筛选项（已删除的活动、最大结果数）
   • 可自定义时区

3. calendar_create_event

   • 创建新的日历活动
   • 支持参会者和通知
   • 可设置地点和描述
   • 支持时区处理

4. calendar_delete_event

   • 按 ID 删除活动
   • 可选择发送取消通知

开发

• TypeScript 源代码位于 src/ 目录下
• 构建输出写入 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：以开发模式启动并自动重新加载

贡献

1. Fork 此仓库
2. 创建功能分支
3. 提交更改
4. 推送到该分支
5. 创建 Pull Request

许可证

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