Google Workspace 工具协议 免费版

通过 @presto-ai/google-workspace-mcp 以OAuth登录访问Google Workspace,无需在Google Cloud Console创建项目或下载client_secret.json。首次使用时弹出浏览器完成Google授权,凭证保存在 ./.config/google-workspace-mcp/. 免费版聚焦基础读取场景,提供邮件检索、日程查看、文件下载与文档表格文本提取能力。所有工具通过同一OAuth凭证访问,无需为每个服务单独配置.

输入格式

参数名	类型	必填	说明
input	string	是	Workspace 工具协议免费版处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY=${API_KEY:?请设置环境变量}

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

核心能力

免费版开放以下读取类工具,均通过 mcporter call --server google-workspace --tool "<tool>" 调用. Gmail 邮件(2项): gmail.search 按Gmail查询语法检索邮件列表,支持 is:unread、from:、after:、label: 等运算符; gmail.get 按 messageId 读取单封邮件正文与元数据. Calendar 日历(2项): calendar.list 列出当前账号所有日历及其ID; calendar.listEvents 按 timeMin/timeMax 区间拉取指定日历的事件,包含标题、时间与参会者. Drive 云盘(2项): drive.search 按文件名或全文内容检索,返回文件ID与基本信息; drive.downloadFile 按 fileId 下载到本地指定路径. Docs 文档(2项): docs.find 检索文档标题或内容; docs.getText 提取文档纯文本,便于后续摘要与检索. Sheets 表格(2项): sheets.getText 读取整表文本; sheets.getRange 按 Sheet1!A1:D20 形式读取指定区域数据. Time 时间(2项): time.getCurrentDate 获取当前日期; time.getTimeZone 获取时区,用于日程时间换算. Auth 鉴权(2项): auth.clear 清除凭证触发重新授权; auth.refreshToken 刷新令牌.

快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

使用流程

1. 环境确认: 确认Agent平台已加载本skill，检查依赖说明中的环境要求
2. 指令输入: 向Agent描述需要执行的任务，引用google-workspace-mcp-free的相关能力
3. 执行处理: Agent按照核心能力章节的指令执行任务
4. 结果验证: 检查输出结果是否符合预期，参考错误处理章节处理异常

安装与授权

npm install -g @presto-ai/google-workspace-mcp
mcporter config add google-workspace --command "npx" --arg "-y" --arg "@presto-ai/google-workspace-mcp" --scope home

首次调用任意工具会打开浏览器请求Google授权,完成后凭证写入 `./.

常用命令

mcporter call --server google-workspace --tool "gmail.search" query="is:unread" maxResults=10
get" messageId="18c1f3a2b5d4e6f7"
mcporter call --server google-workspace --tool "calendar.list"
listEvents" calendarId="primary" timeMin="2026-07-20T00:00:00Z" timeMax="2026-07-20T23:59:59Z"
mcporter call --server google-workspace --tool "drive.search" query="季度财报"
downloadFile" fileId="1A2B3C4D5E6F" localPath="/tmp/report.pdf"
mcporter call --server google-workspace --tool "docs.find" query="会议纪要"
getText" documentId="1A2B3C4D5E6F"
mcporter call --server google-workspace --tool "sheets.getRange" spreadsheetId="1A2B3C4D5E6F" range="Sheet1!A1:D20"
mcporter call --server google-workspace --tool "time.getCurrentDate"

Gmail 查询语法提示

gmail.search 的 query 参数沿用Gmail原生搜索运算符,常用组合:

• is:unread 未读邮件
• from:client@corp.com 指定发件人
• subject:周报 按主题匹配
• after:2026/07/01 指定日期之后
• label:important 按标签过滤
• has:attachment 仅含附件

多个条件用空格连接表示与关系,如 from:manager@corp.com is:unread after:2026/07/01.

文件与文档ID获取

drive.search 与 docs.find 返回结果中包含 fileId/documentId,后续 drive.downloadFile、docs.getText、sheets.getRange 需传入该ID。若已知文档URL,可记录其中 /d/<ID>/ 片段作为ID使用.

适用场景

• 邮件快速检索: 按发件人、主题或未读状态搜索邮件并读取正文,适合收件箱巡查与信息定位。例如查询某客户近一周往来邮件并提取关键诉求.
• 日程查看: 拉取当日或本周日历事件,适合会前确认安排与时间冲突排查。配合 time.getTimeZone 可避免跨时区日程错位.
• 文档资料读取: 跨Drive与Docs检索并提取文本,适合资料查阅与要点摘录。读取Sheets区域数据可用于本地报表或分析.
• 文件下载归档: 将云盘中的PDF或附件下载到本地,便于离线查阅与备份.

使用案例

案例一: 晨会前快速准备

晨会前查看当日日程与未读重要邮件,确认时间安排与待办. 操作:

• time.getTimeZone 确认当前时区,避免日程时间错位
• calendar.listEvents 拉取 calendarId="primary" 当日 09:00-18:00 事件
• gmail.search 查询 is:unread maxResults=10 获取未读邮件列表
• 对关键邮件调用 gmail.get 读取正文,摘录需汇报的要点
• 将日程与邮件要点整理为晨会口头汇报提纲

案例二: 查阅共享文档与表格

定位团队共享的方案文档与数据表,提取文本用于本地分析. 操作:

• drive.search 检索 query="需求方案" 找到目标文件
• docs.find 搜索 query="评审纪要" 后 docs.getText 提取正文
• sheets.getRange 读取配套数据表 Sheet1!A1:D20 区域
• 将文档要点与表格数据合并到本地分析流程

免费版与付费版差异

免费版仅开放读取类工具,适合个人查阅与信息定位。付费版在此基础上提供邮件发送与草稿管理、日程创建与空闲时段查找、文档增改、Chat空间消息、People联系人资料、Slides读取等共49个工具,并配套更完整的异常处理与跨服务编排案例,适合日常办公自动化.

异常处理

• OAuth令牌过期: 工具返回401或未授权时,调用 auth.refreshToken 刷新; 仍失败则 auth.clear 后重新触发浏览器授权.
• 首次授权浏览器未弹出: 确认系统默认浏览器已设置且非headless环境; 远程SSH场景需本地授权后复制 ./.config/google-workspace-mcp/ 目录.
• gmail.search 返回空: 校验查询语法(如 is:unread、from:、after:),放宽时间或标签条件; Gmail查询不支持正则,仅支持其原生搜索运算符.
• drive.downloadFile 写入失败: localPath 所在目录无写权限时更换到 /tmp 或用户目录; 文件过大受Google导出配额限制.
• sheets.getRange 范围超界: 工作表名需与实际一致(默认 Sheet1),区域引用如 Sheet1!A1:B10; 超出已用区域返回空值而非报错. | 错误场景 | 原因 | 处理方式 | |---:|---:|---:| | LLM响应超时或无响应 | 网络延迟或模型负载过高 | 检查网络连接和配置后重试;确认Agent平台LLM服务正常 | | 输入内容格式不正确 | 用户输入不符合skill预期格式 | 对照使用流程章节检查输入格式;参考示例章节修正输入 | | 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述,补充必要的上下文信息 | | 命令执行失败 | 运行环境不满足要求或权限不足 | 对照依赖说明章节确认环境配置;检查命令权限设置 |

常见问题

是否必须创建Google Cloud项目? 不需要。本技能通过托管OAuth绕过Cloud Console建项目、启用API等步骤,只需浏览器登录Google账号即可. 凭证存储在哪里? 如何切换账号? 凭证保存在 ./.config/google-workspace-mcp/。切换账号时执行 auth.clear 清除当前凭证,再次调用工具会触发新账号的浏览器授权. 免费版能发送邮件或创建会议吗? 不能。免费版仅提供读取类工具,发送邮件、创建/修改日程、文档写入等能力需升级到付费版. 支持Google Workspace企业账号吗? 支持,前提是企业管理员未在第三方应用访问策略中禁用相应API scope.

错误处理

错误场景(续)	原因	处理方式
LLM响应超时或无响应	网络延迟或模型负载过高	检查网络连接和配置后重试；确认Agent平台LLM服务正常
输入内容格式不正确	用户输入不符合skill预期格式	检查输入是否符合skill使用说明中的格式要求，参考示例章节
执行结果与预期不符	指令描述不够明确或上下文不足	提供更详细的指令描述，补充必要的上下文信息
命令执行失败	运行环境不满足要求或权限不足	确认运行环境符合依赖说明中的要求；检查命令权限设置

已知限制

• 依赖网络与Google服务可用性,离线不可用.
• OAuth令牌有有效期,长时间未使用可能需重新授权.
• 免费版仅支持读取,无法发送邮件、创建日程或编辑文档.
• 不包含Chat、Slides、People等高级工具.
• Gmail单次搜索maxResults受API上限约束,大批量拉取需分页.

升级提示

当前为免费版,仅开放基础读取能力。升级到付费版 google-workspace-mcp 可解锁全部49个工具,包括Gmail发送与草稿、Calendar会议创建与空闲时段查找、Docs文档增改、Chat空间消息、People联系人资料等,并获取更完整的异常处理与使用案例,适合日常办公自动化与跨服务工作流编排.

输出格式

{
  "success": true,
  "data": {
    "result": "Workspace MCP免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "google-workspace-mcp"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}