managing-google-workspace

Google Workspace——工具路由器

执行模式

检测可用的模式并使用它。

MCP（首选）

如果 google-workspace 服务提供了可用的 MCP 工具，请直接调用。下表中的工具名称是基础名称——根据需要添加服务名称前缀（例如 google-workspace:search_gmail_messages）。

CLI（无 MCP）

如果没有可用的 MCP 工具，请通过 workspace-cli 调用正在运行的服务：

workspace-cli list
workspace-cli call <tool_name> key=value ...

• 仅当工具架构要求时，才传入 user_google_email=USER_EMAIL（适用于未设置 USER_GOOGLE_EMAIL 的旧版 OAuth 2.0）。对于 OAuth 2.1 和可信网关服务，请省略此项，因为它们会从已验证的身份中获取该值。
• 参数采用 key=value 键值对；值会尽可能解析为 JSON，因此请将列表和对象作为 JSON 传递（例如 label_ids='["INBOX"]'）。
• 服务必须可通过 HTTP 访问。默认 URL 为 http://localhost:8000/mcp（通过 --transport streamable-http 启动的服务）；可在子命令前使用 --url 覆盖（workspace-cli --url <url> call ...），或设置 WORKSPACE_MCP_URL。使用 stdio 的插件用户可设置 WORKSPACE_MCP_HTTP_PORT，以在 http://127.0.0.1:<port>/mcp 暴露本地回环旁路服务。
• 如果 workspace-cli 不在 PATH 中，请在本仓库的检出目录中运行 uv run workspace-cli。永久安装（在该检出目录中运行 uv tool install .）是需要用户手动完成的设置步骤。切勿使用 uvx workspace-cli：一个无关且已废弃的 PyPI 软件包占用了这个名称。

调用工具前，请阅读相关参考文件，确认准确的参数名称和类型。仅使用其中有文档说明的参数——不要自行编造参数。

首次设置

如果工具调用因凭据错误而失败，请引导用户完成以下设置。

1. 创建 OAuth 凭据

引导用户前往 Google Cloud Console：

• 创建 OAuth 2.0 客户端 ID（桌面应用类型）
• 启用所需的 Google API（Gmail、Drive、Calendar 等）
• 复制客户端 ID 和客户端密钥

2. 保存凭据

引导用户自行编辑 ~/.claude/settings.local.json（此文件已被 gitignore 忽略，且绝不会共享）。不要让用户在对话中粘贴密钥。告知他们在 env 块中添加以下内容：

{
  "env": {
    "GOOGLE_OAUTH_CLIENT_ID": "their-client-id",
    "GOOGLE_OAUTH_CLIENT_SECRET": "their-secret"
  }
}

如果 settings.local.json 已存在，他们应将内容合并到现有的 env 对象中，而不是替换它。这些环境变量会被 Claude Code 启动的所有 MCP 服务和 CLI 进程继承。

3. 进行身份验证

• MCP 模式：调用 start_google_auth 打开浏览器 OAuth 流程
• CLI 模式：运行任意工具——首次调用时会打开 OAuth 流程
• 凭据会缓存到 ~/.google_workspace_mcp/credentials（或由 WORKSPACE_MCP_CREDENTIALS_DIR 配置的位置），供后续会话使用

有关服务选项、传输方式、身份验证模式、工具筛选和部署的信息，请参阅：references/server-options.md

通用模式

• 整合式“manage”工具通过 action 参数执行创建／更新／删除操作。

工具参考

Gmail

任务	工具
搜索／查找邮件	search_gmail_messages
阅读一封邮件	get_gmail_message_content
阅读多封邮件	get_gmail_messages_content_batch
阅读一个邮件会话	get_gmail_thread_content
阅读多个邮件会话	get_gmail_threads_content_batch
发送邮件（新邮件或回复）	send_gmail_message
创建草稿	draft_gmail_message
下载附件	get_gmail_attachment_content
添加／移除标签（单个）	modify_gmail_message_labels
添加／移除标签（批量）	batch_modify_gmail_message_labels
管理标签	manage_gmail_label
列出标签	list_gmail_labels
管理过滤器	manage_gmail_filter
列出过滤器	list_gmail_filters

参数说明：references/gmail.md

Google Drive

任务	工具
搜索文件/文件夹	search_drive_files
列出文件夹中的项目	list_drive_items
读取文件内容	get_drive_file_content
下载文件	get_drive_file_download_url
创建文件	create_drive_file
创建文件夹	create_drive_folder
复制文件	copy_drive_file
更新文件元数据	update_drive_file
分享/设置权限	set_drive_file_permissions
管理访问权限（添加/移除）	manage_drive_access
检查权限	get_drive_file_permissions
获取可分享链接	get_drive_shareable_link
检查公开访问权限	check_drive_file_public_access
将文件导入 Google Doc	import_to_google_doc
将电子表格（XLSX、CSV……）导入 Google Sheets	import_to_google_sheets
将演示文稿（PPTX……）导入 Google Slides	import_to_google_slides

参数请参阅：references/drive.md

Google Calendar

任务	工具
列出日历	list_calendars
创建辅助日历	create_calendar
获取事件	get_events
创建/更新/删除事件	manage_event
办公地点（自动拒绝）	manage_out_of_office
专注时间（自动拒绝、免打扰）	manage_focus_time
检查空闲情况	query_freebusy

参数请参阅：references/calendar.md

Google Docs

任务	工具
将文档读取为 Markdown	get_doc_as_markdown
读取文档内容（原始格式）	get_doc_content
读取包含链接/智能芯片目标和文档片段的纯文本	get_doc_content(preserve_context=True)
创建新文档	create_doc
修改文本/应用样式（按索引或 heading）	modify_doc_text
插入元素（表格、列表、分隔符）	insert_doc_elements
插入图片	insert_doc_image
创建包含数据的表格	create_table_with_data
更新段落样式	update_paragraph_style
查找并替换	find_and_replace_doc
检查结构	inspect_doc_structure
批量更新（多个操作）	batch_update_doc
页眉/页脚	update_doc_headers_footers
管理标签页	manage_doc_tab
导出为 PDF	export_doc_to_pdf
列出文件夹中的文档	list_docs_in_folder
搜索文档	search_docs
评论	manage_document_comment / list_document_comments
调试表格结构	debug_table_structure

参数请参阅：references/docs.md

Google Sheets

任务	工具
读取单元格值	read_sheet_values
写入/追加/清除值	modify_sheet_values
插入智能芯片	modify_sheet_values (chips)
设置单元格格式	format_sheet_range
条件格式	manage_conditional_formatting
获取电子表格信息	get_spreadsheet_info
创建电子表格	create_spreadsheet
创建工作表（标签页）	create_sheet
重命名/删除/隐藏/重新排序/设置标签页样式	manage_sheet_tab
调整大小/冻结/隐藏/插入/删除行和列	resize_sheet_dimensions
在工作表之间移动行	move_sheet_rows
列出结构化表格	list_sheet_tables
向结构化表格追加行	append_table_rows
管理命名范围	manage_named_range
列出电子表格	list_spreadsheets
评论	manage_spreadsheet_comment / list_spreadsheet_comments

参数请参阅：references/sheets.md

Google 幻灯片

任务	工具
获取演示文稿	get_presentation
获取指定幻灯片	get_page
查看幻灯片（渲染为图像）	render_page_to_image
创建演示文稿	create_presentation
批量更新	batch_update_presentation
演讲者备注	get_presentation (include_speaker_notes) + batch_update_presentation
评论	manage_presentation_comment / list_presentation_comments

参数说明：references/slides.md

Google 表单

任务	工具
获取表单	get_form
创建表单	create_form
批量更新表单	batch_update_form
列出回复	list_form_responses
获取单条回复	get_form_response
发布设置	set_publish_settings

参数说明：references/forms.md

Google Tasks

任务	工具
列出任务列表	list_task_lists
获取任务列表	get_task_list
管理任务列表（CRUD）	manage_task_list
列出任务	list_tasks
获取任务	get_task
管理任务（CRUD/移动）	manage_task

参数说明：references/tasks.md

Google 联系人

任务	工具
搜索联系人	search_contacts
获取联系人	get_contact
管理联系人（CRUD）	manage_contact
批量管理联系人	manage_contacts_batch
列出联系人群组	list_contact_groups
获取联系人群组	get_contact_group
管理联系人群组	manage_contact_group
列出所有联系人	list_contacts

参数说明：references/contacts.md

Google Chat

任务	工具
列出空间	list_spaces
获取消息	get_messages
搜索消息	search_messages
发送消息	send_message
编辑已发送的消息	send_message (message_name)
对消息做出回应	create_reaction
下载附件	download_chat_attachment

参数说明：references/chat.md

Google Apps Script

任务	工具
项目/文件（列出/获取）	get_script_project (action)
项目（创建/删除）	manage_script_project (action)
文件内容（更新）	manage_script_content (action="update")
运行函数	run_script_function
生成触发器代码	generate_trigger_code
部署（列出）	list_script_deployments
部署（创建/更新/删除）	manage_deployment (action)
版本（列出/获取）	get_script_version (action)
版本（创建）	manage_script_version (action="create")
执行指标 / 进程历史记录	get_script_activity (action="metrics" / "processes")
当前用户的触发器（列出/删除）	manage_script_trigger (action)

参数说明：references/apps-script.md

Google 自定义搜索

任务	工具
网页搜索	search_custom
获取搜索引擎信息	get_search_engine_info

参数说明：references/search.md

身份验证

任务	工具
启动 OAuth 流程	start_google_auth

仅适用于旧版 OAuth 2.0 —— 启用 OAuth 2.1 时会禁用。大多数情况下，只需调用所需工具，身份验证便会自动完成。参数说明：references/server-options.md

常见工作流

回复电子邮件

1. search_gmail_messages —— 查找电子邮件
2. get_gmail_message_content —— 阅读邮件（获取 message_id 和 thread_id）
3. send_gmail_message —— 使用 thread_id 回复；省略回复标头，以将回复发送到最新的非草稿、非垃圾邮件消息（该消息具有 RFC Message-ID）

查找并分享文件

1. search_drive_files —— 查找文件
2. manage_drive_access —— 分享文件
3. get_drive_shareable_link —— 获取链接

读取并更新电子表格

1. get_spreadsheet_info -- 获取工作表名称
2. read_sheet_values -- 读取当前数据
3. modify_sheet_values -- 写入更新后的数据
4. read_sheet_values -- 验证更新

创建格式化文档

1. create_doc -- 创建文档
2. modify_doc_text -- 添加带格式的文本
3. insert_doc_elements -- 添加表格、列表和分页符
4. update_paragraph_style -- 应用标题样式
5. get_doc_as_markdown -- 验证结果

处理电子邮件附件

1. search_gmail_messages -- 查找电子邮件
2. get_gmail_message_content -- 获取附件元数据
3. get_gmail_attachment_content -- 下载附件

编辑 Google Doc

1. get_doc_as_markdown -- 读取当前内容
2. inspect_doc_structure -- 查找插入位置和索引
3. modify_doc_text / insert_doc_elements -- 进行修改
4. get_doc_as_markdown -- 验证结果

提示

• 检查参数：参考文件记录了每个工具的所有参数。在 CLI 模式下，workspace-cli list 会显示正在运行的服务开放了哪些工具。