AI导哈

Google Workspace MCP服务器

提供对Google Workspace服务的只读访问的模型上下文协议（MCP）服务器。

  • by jacob-bd
  • Python
  • 本地部署
  • 16 星标
  • 更新于
在 GitHub 查看 jacob-bd/google-workspace-mcp

使用说明

谷歌工作区MCP服务器

一种模型上下文协议（MCP）服务器，提供对Google Workspace服务的只读访问。

这有什么不同？

此MCP提供 两种身份验证选项 根据您的设置：

选项1:ADC（建议企业使用）

  • 使用gcloud CLI（与Terraform、其他谷歌工具相同）
  • 非常适合具有现有gcloud设置的企业用户
  • 需要启用工作区API的配额项目
  • 无需额外设置 如果您已经配置了gcloud

选项2:OAuth（用于个人Gmail）

  • 适用于没有gcloud的个人Gmail帐户
  • 需要一次性设置：在Google Cloud Console中创建自己的OAuth凭据（约5分钟）
  • 代币安全存储在 ~/.config/g-workspace-mcp/

这两个选项都适用于个人Gmail帐户和企业Google Workspace帐户。

特征

  • Google 云端硬盘：搜索文件、列出文件夹、读取文档内容
  • Gmail：搜索电子邮件、阅读邮件、列出标签
  • 谷歌日历：列出日历，获取事件
  • 谷歌表格：读取电子表格数据

所有访问权限均为 只读 为了安全。

需求

  • Python 3.11+
  • 紫外线 -快速Python包管理器(安装)
  • 谷歌云CLI -仅ADC身份验证需要（OAuth不需要）

快速开始

1.安装uv（如果尚未安装）

curl -LsSf https://astral.sh/uv/install.sh | sh

2.安装MCP服务器

git clone https://github.com/jacob-bd/google-workspace-mcp.git
cd google-workspace-mcp
uv tool install .

这将在隔离环境中全局安装CLI。安装后，您可以删除 google-workspace-mcp 文件夹。

3.安装Google Cloud CLI（如果尚未安装）

macOS：

brew install --cask google-cloud-sdk

Linux（Fedora/RHEL）：

sudo dnf install google-cloud-cli

Linux（Ubuntu/Debian）：

sudo apt-get install google-cloud-cli

4.身份验证

选择您的身份验证方法：

  • ADC（企业）：如果你安装了gcloud，只需运行 g-workspace-mcp setup --adc
  • OAuth（个人Gmail）：首先创建OAuth凭据（请参阅下一节），然后运行 g-workspace-mcp setup --oauth

创建OAuth凭据（适用于个人Gmail用户）

如果您使用OAuth而不是ADC，则需要在Google Cloud Console中创建自己的OAuth凭据。这是一个一次性设置，大约需要5分钟。

视频演练

观看此演示，了解GCP OAuth设置过程和实际使用的工具：

单击上图在新窗口中打开视频。

第一步：创建谷歌云项目

  1. 首选 谷歌云控制台
  2. 单击页面顶部的项目下拉列表
  3. 点击 新项目
  4. 输入项目名称（例如“工作区MCP”）
  5. 点击 创建
  6. 等待项目创建，然后从下拉列表中选择它

步骤2：启用API

  1. 首选 API和服务 > 图书馆 （或 点击此处)
  2. 搜索并启用以下每个API：
    • Google Drive API
    • Gmail API
    • 谷歌日历API
    • 谷歌网页API

步骤3：配置OAuth同意屏幕

  1. 首选 API和服务 > OAuth同意屏幕
  2. 选择 外部 然后单击 创建
  3. 填写必填字段：
    • 应用程序名称：“工作区MCP”（或您喜欢的任何名称）
    • 用户支持电子邮件：您的电子邮件地址
    • 开发人员联系电子邮件：您的电子邮件地址
  4. 点击 保存并继续
  5. 在 范围 页面，单击 添加或删除作用域
  6. 添加这些范围（搜索或粘贴网址）：
    • https://www.googleapis.com/auth/drive.readonly
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/calendar.readonly
    • https://www.googleapis.com/auth/spreadsheets.readonly
  7. 点击 更新那么 保存并继续
  8. 在 测试用户 页面，单击 添加用户
  9. 添加您自己的电子邮件地址
  10. 点击 保存并继续那么 返回仪表盘

步骤4：创建OAuth客户端ID

  1. 首选 API和服务 > 凭证
  2. 点击 +创建凭据 > OAuth客户端ID
  3. 选择 桌面应用程序 作为应用程序类型
  4. 输入名称（例如，“工作区MCP桌面”）
  5. 点击 创建

步骤5：下载并保存凭据

  1. 弹出窗口将显示您的客户端ID和客户端密码
  2. 点击 下载JSON （重要提示：立即执行此操作，以后将无法下载密钥！）
  3. 移动到 ~/.config/g-workspace-mcp/client_secret.json 使用下面的命令（这也会为您重命名文件）

在macOS/Linux上：

mkdir -p ~/.config/g-workspace-mcp
mv ~/Downloads/client_secret*.json ~/.config/g-workspace-mcp/client_secret.json

提示： 下载的文件有一个长名称，如 client_secret_123...googleusercontent.com.json。上面的命令会自动匹配它并重命名它。如果 mv 命令显示“不匹配”，打开下载文件夹并手动拖动文件，或复制确切的文件名：

mv ~/Downloads/<paste-exact-filename>.json ~/.config/g-workspace-mcp/client_secret.json

步骤6：运行安装程序

g-workspace-mcp setup --oauth

这将打开您的浏览器，使用您的Google帐户登录。授权后，一切就绪！

备注：您将看到一条警告，指出该应用程序“未经验证”。这对于个人OAuth应用程序来说是正常的。点击 高级 > 转到工作区MCP（不安全） 继续。这是安全的，因为你自己创建了应用程序。

5.身份验证（ADC方法-企业用户）

如果您已安装并配置了gcloud，请运行：

g-workspace-mcp setup --adc

这将：

  1. 检查gcloud命令行界面 -验证是否已安装
  2. 检查现有凭据 -显示文件位置和任何配置 quota_project
  3. 测试API访问 -验证您的凭据是否具有所需的范围
  4. 如果需要，重新进行身份验证 -在重新验证之前创建现有凭据的备份

就是这样！ 如果你已经为gcloud设置了配额项目，那么你就可以开始了。

6.配置您的AI工具

# See available options
g-workspace-mcp config

# Configure Claude Code
g-workspace-mcp config -f claude

# Configure Gemini CLI
g-workspace-mcp config -f gemini

# Get JSON config for Cursor or other tools
g-workspace-mcp config -f cursor

# Get universal JSON format for other AI IDEs
g-workspace-mcp config -f json

该命令将显示它将要执行的操作并要求确认。

没有要运行的服务器！ Claude Code通过stdio按需生成流程。

身份验证详细信息

此MCP支持两种身份验证方法。使用适合您设置的选项。

OAuth令牌存储

OAuth令牌安全地存储在：

  • 位置: ~/.config/g-workspace-mcp/token.json
  • 权限：600（仅限所有者读/写）
  • 刷新：令牌过期时自动刷新

ADC令牌存储

ADC令牌存储在：

  • Linux/macOS: ~/.config/gcloud/application_default_credentials.json

当使用ADC重新进行身份验证时，setup命令会自动备份您现有的凭据：

~/.config/gcloud/application_default_credentials.json.backup.<timestamp>

令牌生命周期

  • 访问令牌 最近1小时和自动刷新
  • 刷新令牌 持续使用至撤销或未使用6个月
  • 如果身份验证过期，请运行 g-workspace-mcp setup 再次

CLI命令

# Set up authentication (interactive - prompts to choose method)
g-workspace-mcp setup

# Set up with specific method
g-workspace-mcp setup --oauth          # OAuth flow (requires client_secret.json)
g-workspace-mcp setup --adc            # ADC/gcloud flow (for enterprise users)

# Configure MCP for AI tools (default: system-wide)
g-workspace-mcp config -f <claude|cursor|gemini|json>
g-workspace-mcp config -f claude -s project      # Project-level instead

# Check authentication status
g-workspace-mcp status

# Remove stored credentials
g-workspace-mcp logout                 # Remove OAuth token
g-workspace-mcp logout --all           # Also show ADC removal instructions

# Run MCP server (called by AI tools automatically)
g-workspace-mcp run

可用工具

驱动工具

工具 说明
drive_search 使用可选类型筛选器按查询搜索文件
drive_list 列出文件夹中的文件
drive_list_recursive 递归列出文件夹树中所有文件的大小
drive_get_content 获取文件内容（文档、表格、文本文件）

Gmail工具

工具 说明
gmail_search 使用Gmail查询语法搜索电子邮件
gmail_get_message 通过邮件ID获取完整的电子邮件内容
gmail_list_labels 列出所有Gmail标签

日历工具

工具 说明
calendar_list 列出所有可访问的日历
calendar_get_events 获取日期范围内的事件

图纸工具

工具 说明
sheets_read 从电子表格区域读取数据

AI工具的配置

克劳德代码

选项1：使用g-workspace-mcp（推荐）

# Add system-wide (default)
g-workspace-mcp config -f claude

# Or add project-level
g-workspace-mcp config -f claude -s project

这将向您显示命令，并在运行之前请求确认。

选项2：手动配置

添加 ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "g-workspace-mcp",
      "args": ["run"]
    }
  }
}

验证安装：

claude mcp list

或者使用 /mcp Claude Code中的命令，用于验证服务器是否已配置。

光标

添加到光标MCP设置：

{
  "google-workspace": {
    "command": "g-workspace-mcp",
    "args": ["run"]
  }
}

Gemini CLI

选项1：使用g-workspace-mcp（推荐）

# Add system-wide (default)
g-workspace-mcp config -f gemini

# Or add project-level
g-workspace-mcp config -f gemini -s project

这将向您显示命令，并在运行之前请求确认。

选项2：手动配置

为了 系统范围的 访问，添加到 ~/.gemini/settings.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "g-workspace-mcp",
      "args": ["run"]
    }
  }
}

为了 项目级 访问，添加到 .gemini/settings.json 在您的项目目录中：

{
  "mcpServers": {
    "google-workspace": {
      "command": "g-workspace-mcp",
      "args": ["run"]
    }
  }
}

验证安装：

gemini mcp list

其他AI IDE（JSON格式）

对于上面未列出的工具，请使用JSON格式获取通用配置：

g-workspace-mcp config -f json

这将输出适用于任何AI IDE的标准MCP服务器配置：

{
  "google-workspace": {
    "command": "g-workspace-mcp",
    "args": ["run"]
  }
}

将其添加到IDE的MCP配置文件中（有关确切位置和格式，请参阅IDE的文档）。

环境变量

变量 默认值 描述
LOG_LEVEL INFO 日志记录级别

安全

  • 所有API作用域都是 只读 为了安全
  • OAuth令牌存储在 600权限 （仅限所有者读/写）
  • 没有要管理或共享的凭据文件
  • 客户端机密（如果使用OAuth）永远不应该提交给git

隐私

此MCP可以 不 收集、存储或传输任何用户数据：

  • 无数据记录 -操作日志（发送到stderr，从不发送stdout）仅包含元数据（计数、ID），从不包含电子邮件或文件内容
  • 无数据存储 -您的电子邮件、文件和日历事件永远不会写入磁盘
  • 无遥测 -零分析、跟踪或使用报告
  • 直接数据流 -数据直接从Google API流向您的AI工具

本地存储的唯一文件是您的OAuth令牌(~/.config/g-workspace-mcp/token.json)用于身份验证目的。

故障排除

“未配置谷歌身份验证”

运行安装命令：

g-workspace-mcp setup

“身份验证已过期，无法刷新”

重新验证：

g-workspace-mcp setup

“ModuleNotFoundError:没有名为'google.auth'的模块或类似的导入错误

如果你在尝试直接运行Python文件时看到导入错误， 不运行源文件. MCP服务器作为CLI工具安装。始终使用：

g-workspace-mcp status   # Check authentication
g-workspace-mcp run      # Run the server

不要尝试直接运行源文件：

# These will fail:
python3 g_workspace_mcp/src/cli.py status  # WRONG
python3 -m g_workspace_mcp.src.cli status  # WRONG

检查状态

g-workspace-mcp status

发展

# Install in editable mode (for development - requires keeping the folder)
uv pip install -e ".[dev]"

# Run directly
uv run python -m g_workspace_mcp.src.main

振动编码警报

完全透明：该项目由非开发人员使用AI编码助手构建。如果你是一个经验丰富的Python开发人员，你可能会看看这个代码库和wince。没关系。

这里的目标是解决一个棘手的问题——从人工智能工具只读访问谷歌工作区——并在此过程中学习。代码可以工作，但它可能缺少只有多年经验才能提供的模式、优化或优雅。

许可证

麻省理工学院

相关 MCP