AI导哈

Google Workspace MCP服务器

一个通过MCP协议与Gmail和Google Calendar交互的服务器，支持多账户管理和批量操作。

  • by j3k0
  • TypeScript
  • 本地部署
  • 31 星标
  • 更新于
在 GitHub 查看 j3k0/mcp-google-workspace

使用说明

MCP谷歌工作空间服务器

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

特性

  • 多个Google帐户支持

    • 在多个Google帐户之间使用和切换
    • 每个帐户都可以有自定义元数据和描述

  • Gmail集成

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

  • 日历集成

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

示例提示

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

Gmail

  • “检索我最近未读的邮件”
  • “搜索Scrum Master的电子邮件”
  • “从会计中检索所有电子邮件”
  • “接收关于ABC的电子邮件并对其进行总结”
  • “为Alice的最后一封电子邮件写一封漂亮的回复，并上传一份草稿”
  • “用感谢信回复Bob的电子邮件。将其存储为草稿”

日历

  • “我明天的议程上有什么？”
  • “查看我的私人帐户下周的家庭日程”
  • “我需要和蒂姆一起计划下周2小时的活动。建议一些时间段”

先决条件

  • Node.js>=20
  • 启用了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凭据：

    • 去 谷歌云控制台
    • 创建新项目或选择现有项目
    • 为您的项目启用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": "your.email@gmail.com",
      "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 -- user@gmail.com

# Force re-authentication (e.g. after OAuth scope changes)
npm run authenticate -- user@gmail.com --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桌面配置

配置Claude Desktop以使用mcp谷歌工作区服务器：

在MacOS上：编辑 ~/Library/Application\ Support/Claude/claude_desktop_config.json

在Windows上：编辑 %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration 
{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "<dir_to>/mcp-google-workspace/launch"
    }
  }
}
Published Servers Configuration 
{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "npx",
      "args": [
        "mcp-google-workspace"
      ]
    }
  }
}

码头工人

您还可以在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的查询语法搜索电子邮件（例如，'是：未读'，'来自：example@gmail.com'，'newer_than:2d'，'具有：附件'）
    • 按逆时间顺序返回电子邮件
    • 包括元数据和内容摘要

  2. gmail_get_email

    • 按ID检索完整的电子邮件内容
    • 包括完整的邮件正文和附件信息

  3. gmail_bulk_get_emails

    • 在单个请求中按ID检索多封电子邮件
    • 高效的批量处理

  4. gmail_create_draft

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

  5. gmail_delete_draft

    • 删除电子邮件草稿 draft_id
    • 注： draft_id 与返回的消息ID不同 gmail_query_emails.使用 gmail_list_drafts 为了获得它。

  6. gmail_list_drafts

    • 列出Gmail草稿，可根据Gmail搜索查询进行筛选
    • 返回每份草稿 draft_id （需要 gmail_delete_draft)旁边 message_id、主题、收件人和片段

  7. gmail_reply

    • 回复现有电子邮件
    • 可选择立即发送或另存为草稿
    • 通过CC支持“全部回复”

  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. 分叉存储库
  2. 创建要素分支
  3. 提交您的更改
  4. 推到分支
  5. 创建拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

相关 MCP