使用说明

谷歌工作区MCP服务器

通过模型上下文协议（MCP）将Claude连接到Google Workspace API。

特性

116个MCP工具 跨7个谷歌工作区API：

服务	工具	功能
Gmail	27	搜索、发送、回复、草稿、标签、过滤器、格式化、批处理操作，附件
日历	8	列出日历、创建/更新/删除事件、管理与会者、忙/闲
驾驶	17	搜索、上传/下载二进制文件、文件夹、权限、同步（rclone集成）
文档	17	创建、编辑、格式化文本/段落、表格、列表、选项卡、评论
表格	12	创建、读取、写入、格式化单元格、图表、合并、条件格式化
幻灯片	21	创建演示文稿、幻灯片、格式化文本、背景、布局
任务	13	任务列表、创建/更新/完成任务、子任务、搜索

亮点

完整的Gmail管理：使用高级查询进行搜索，使用文件附件发送/回复，使用标签、过滤器、丰富的HTML格式进行组织，批处理操作
传输：通过本地路径将任何文件类型上传到驱动器；将Drive文件和Gmail附件下载到磁盘
日历集成：与与会者一起创建活动，管理多个日历，处理时区，检查可用性
驾驶操作：使用可选的rclone同步搜索文件、管理文件夹、权限、上传/下载
谷歌文档：创建和编辑文档、富文本格式、表格、列表、选项卡、评论、美人鱼图
谷歌表格：创建电子表格、设置单元格格式、图表、条件格式、合并单元格、数字格式
谷歌幻灯片：创建演示文稿、格式化文本、添加图像/文本框、背景、布局、项目符号列表
任务API：具有列表、子任务、截止日期和跨列表搜索的完整任务管理

二进制文件传输（v0.3.0）

使用任何文件类型，而不仅仅是文本：

# Upload a JPEG to Drive
upload_drive_file(local_path="/path/to/photo.jpg", parent_id="<folder-id>")

# Download a Drive file to disk (PDF, image, etc.)
get_drive_file_content(file_id="<id>", save_path="/tmp/report.pdf")

# Send an email with attachments
send_email(to="...", subject="...", body="...", attachments=["/path/to/file.pdf"])

# List attachments in a received email
get_gmail_message_content(message_id="<id>")
# → response includes: attachments: [{filename, mimeType, size, attachmentId}, ...]

# Download a Gmail attachment
download_gmail_attachment(message_id="<id>", attachment_id="<att-id>", save_path="/tmp/file.pdf")

格式化功能

支援多文本格式编写：在文档、幻灯片和Gmail中应用粗体、斜体、下划线、颜色和字体
高级单元格格式化：图纸中的背景颜色、边框、数字格式、条件格式
专业演示：幻灯片中的自定义布局、格式化文本框、背景和项目符号列表
HTML电子邮件创建：专业电子邮件通信的丰富格式

安装

pip install gworkspace-mcp

或与紫外线:

uv pip install gworkspace-mcp

发展：

git clone https://github.com/masapasa/google-workspace-mcp.git
cd google-workspace-mcp
pip install -e ".[dev]"

快速开始

1.设置Google Cloud凭据

首选谷歌云控制台
创建新项目或选择现有项目
启用以下API：
- Gmail API
- 谷歌日历API
- Google Drive API
- 谷歌文档API
- 谷歌网页API
- 谷歌幻灯片API
- 谷歌任务API
创建OAuth 2.0凭据（桌面应用程序）
下载并记录您的客户端ID和客户端密码

2.身份验证

# Set your credentials
export GOOGLE_OAUTH_CLIENT_ID='your-client-id'
export GOOGLE_OAUTH_CLIENT_SECRET='your-client-secret'  # pragma: allowlist secret

# Run OAuth flow (opens browser)
workspace setup

# Verify authentication
workspace doctor

3.启动MCP服务器

workspace mcp

4.连接到克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-workspace": {
      "command": "workspace",
      "args": ["mcp"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"  // pragma: allowlist secret
      }
    }
  }
}

重新启动Claude Desktop以激活。

多账户支持

多个谷歌帐户可以配置为命名配置文件，让您在个人和工作帐户之间切换，而无需重新进行身份验证。

设置多个帐户

# Set up a named profile (opens browser for each account)
workspace setup --account personal@gmail.com
workspace setup --account work@company.com

# List all configured profiles
workspace accounts list

# Switch the default profile
workspace accounts default work@company.com

# Remove a profile
workspace accounts remove personal@gmail.com

# Check authentication status for a specific account
workspace doctor --account work@company.com

每次工具调用使用帐户

每个MCP工具都接受一个可选 account 参数：

search_gmail_messages(query="budget", account="work@company.com")
get_events(calendar_id="primary", account="personal@gmail.com")

帐户解析顺序

当 account 如果未指定，服务器将按以下顺序选择帐户：

account 工具调用中的参数（显式，最高优先级）
GWORKSPACE_ACCOUNT 环境变量（会话范围覆盖）
通过设置默认配置文件 workspace accounts default
回退到 "gworkspace-mcp" （与现有令牌向后兼容）

会话范围内的帐户覆盖

集 GWORKSPACE_ACCOUNT 要使会话中的所有工具调用都使用特定帐户而无需传递 account 每次：

export GWORKSPACE_ACCOUNT=work@company.com
workspace mcp

列出已配置的帐户

这 list_accounts MCP工具返回所有已配置的配置文件：

list_accounts()
# → [{email, is_default, created_at}, ...]

存储格式

所有配置文件都存储在 ~/.gworkspace-mcp/tokens.json。格式向后兼容——现有的单帐户令牌继续工作，不做任何更改：

{
  "gworkspace-mcp": { ... },
  "work@company.com": { ... },
  "personal@gmail.com": { ... }
}

认证

OAuth 2.0流程

此服务器使用OAuth 2.0通过Google API进行安全身份验证。身份验证流程：

workspace setup 打开浏览器以获得谷歌同意
您授权访问Gmail、日历、驱动器、文档、表格、幻灯片和任务
令牌安全地存储在本地
令牌过期时自动刷新

所需范围

服务器请求以下OAuth作用域：

范围	目的
`https://www.googleapis.com/auth/gmail.modify`	阅读、发送和整理Gmail
`https://www.googleapis.com/auth/calendar`	完全日历访问
`https://www.googleapis.com/auth/drive`	完全驱动器访问权限
`https://www.googleapis.com/auth/documents`	读写谷歌文档
`https://www.googleapis.com/auth/spreadsheets`	读写谷歌表格
`https://www.googleapis.com/auth/presentations`	读写谷歌幻灯片
`https://www.googleapis.com/auth/tasks`	完整任务访问权限

令牌存储

代币存储在： ~/.gworkspace-mcp/tokens.json

此文件包含您的OAuth令牌。保持安全，不要分享。

可用工具

Gmail（26个工具）

工具	说明
`search_gmail_messages`	使用Gmail查询语法搜索邮件
`get_gmail_message_content`	按ID获取完整消息内容
`send_email`	发送新电子邮件
`reply_to_email`	回复现有帖子
`create_draft`	将电子邮件另存为草稿
`list_gmail_labels`	列出所有标签（系统和自定义）
`create_gmail_label`	创建自定义标签
`delete_gmail_label`	删除自定义标签
`modify_gmail_message`	在邮件中添加/删除标签
`archive_gmail_message`	将邮件存档（从收件箱中删除）
`trash_gmail_message`	将邮件移至垃圾箱
`untrash_gmail_message`	从回收站还原邮件
`mark_gmail_as_read`	将邮件标记为已读
`mark_gmail_as_unread`	将邮件标记为未读
`star_gmail_message`	在消息中添加星号
`unstar_gmail_message`	从消息中删除星号
`batch_modify_gmail_messages`	批量添加/删除标签
`batch_archive_gmail_messages`	批量存档邮件
`batch_trash_gmail_messages`	大量垃圾信息
`batch_mark_gmail_as_read`	批量标记为已读
`batch_delete_gmail_messages`	永久删除邮件（注意！）
`format_email_content`	使用HTML样式设置电子邮件内容的格式
`set_email_signature`	设置Gmail签名的格式
`create_formatted_email`	创建格式丰富的HTML电子邮件
`list_gmail_filters`	列出所有Gmail过滤器
`create_gmail_filter`	创建新的Gmail过滤器
`delete_gmail_filter`	删除Gmail过滤器
`get_vacation_settings`	获取假期自动回复设置
`set_vacation_settings`	配置假期自动应答器

日历（8工具）

工具	说明
`list_calendars`	列出所有可访问的日历
`create_calendar`	创建新日历
`update_calendar`	更新日历属性
`delete_calendar`	删除日历
`get_events`	获取时间范围内的事件
`create_event`	创建新事件
`update_event`	更新现有事件
`delete_event`	删除事件
`query_free_busy`	检查与会者的可用性

驱动器（17个工具）

工具	说明
`search_drive_files`	使用驱动器查询语法搜索文件
`get_drive_file_content`	获取文件内容（文本文件）
`create_drive_folder`	创建新文件夹
`upload_drive_file`	上传文本文件
`delete_drive_file`	删除文件或文件夹
`move_drive_file`	将文件移动到其他文件夹
`list_drive_contents`*	列出文件夹内容
`download_drive_folder`*	将文件夹下载到本地文件系统
`upload_to_drive`*	将本地文件夹上载到驱动器
`sync_drive_folder`*	本地和驱动器之间的同步

*需要 rclone 待安装

表格（12个工具）

工具	说明
`create_spreadsheet`	创建新的谷歌电子表格
`get_spreadsheet_data`	获取电子表格元数据和结构
`list_spreadsheet_sheets`	在电子表格中列出所有工作表
`get_sheet_values`	从特定工作表/范围获取值
`update_sheet_values`	用新值更新特定单元格
`append_sheet_values`	将行附加到工作表末尾数据
`clear_sheet_values`	清除某个范围内的值
`format_cells`	应用格式（颜色、字体、边框）
`set_number_format`	设置数字格式（货币、百分比、日期）
`merge_cells`	跨范围合并单元格
`set_column_width`	调整列宽
`create_chart`	根据数据创建图表（条形图、折线图、饼图）

幻灯片（21个工具）

工具	说明
`create_presentation`	创建新的Google幻灯片演示文稿
`get_presentation`	获取演示文稿元数据和结构
`list_presentations`	列出可访问的演示文稿
`get_presentation_text`	从演示文稿中提取所有文本
`get_slide`	获取特定幻灯片内容
`add_slide`	添加带有布局的新幻灯片
`delete_slide`	删除幻灯片
`update_slide_text`	更新幻灯片形状中的文本
`format_text_in_slide`	将文本格式应用于幻灯片内容
`add_formatted_text_box`	添加具有自定义格式的文本框
`add_text_box`	向幻灯片添加基本文本框
`set_slide_background`	设置幻灯片背景颜色或图像
`create_bulleted_list_slide`	使用项目符号列表创建幻灯片
`apply_slide_layout`	将预定义布局应用于幻灯片
`add_image`	将URL中的图像添加到幻灯片

文档（17个工具）

工具	说明
`create_document`	创建新的Google文档
`get_document`	获取文档内容和结构
`append_to_document`	在文档中添加文本
`upload_markdown_as_doc`	将Markdown转换为谷歌文档
`list_document_comments`	列出文档上的所有评论
`add_document_comment`	向文档添加注释
`reply_to_comment`	对现有评论的回复
`list_document_tabs`	列出文档中的所有选项卡
`get_tab_content`	从特定选项卡获取内容
`create_document_tab`	创建新选项卡
`update_tab_properties`	更新选项卡标题或图标
`move_tab`	将选项卡移动到新位置
`render_mermaid_to_doc`	渲染美人鱼图并插入到文档中
`format_text_in_document`	应用文本格式（粗体、斜体、颜色、字体）
`format_paragraph_in_document`	应用段落格式（对齐、间距）
`create_list_in_document`	创建项目符号或编号列表
`insert_table_in_document`	插入具有自定义尺寸的表
`apply_heading_style`	应用标题样式（H1、H2等）
`set_document_margins`	配置文档边距
`publish_markdown_to_doc`	将降价内容发布为谷歌文档

账户（1个工具）

工具	说明
`list_accounts`	列出所有已配置的配置文件，包括电子邮件、is_default和created_at

任务（13个工具）

工具	说明
`list_task_lists`	列出所有任务列表
`get_task_list`	获取特定任务列表
`create_task_list`	创建新任务列表
`update_task_list`	更新任务列表标题
`delete_task_list`	删除任务列表
`list_tasks`	在列表中列出任务
`get_task`	获取特定任务
`search_tasks`	在所有列表中搜索任务
`create_task`	创建新任务
`update_task`	更新任务详细信息
`complete_task`	将任务标记为已完成
`delete_task`	删除任务
`move_task`	移动任务或将其设为子任务

CLI命令

# Authenticate with Google (default profile)
workspace setup

# Authenticate a named profile
workspace setup --account NAME

# Check authentication status and dependencies
workspace doctor

# Check status for a specific account
workspace doctor --account NAME

# Manage named profiles
workspace accounts list          # show all profiles with default marker
workspace accounts default NAME  # switch the default profile
workspace accounts remove NAME   # remove a profile

# Start the MCP server (for Claude Desktop)
workspace mcp

# Show version
workspace --version

# Show help
workspace --help

文档

有关详细文档，请参阅 docs/ 目录：

入门指南 -安装、身份验证、快速入门
用户指南 -Claude桌面集成，CLI参考
API 参考 -所有116个工具的完整工具文档
发展 -贡献、测试、发布

发展

# Clone and install
git clone https://github.com/masapasa/google-workspace-mcp.git
cd google-workspace-mcp
pip install -e ".[dev]"

# Run tests
pytest

# Code quality
ruff format src tests && ruff check src tests && mypy src

看贡献指南用于完整的开发设置。

需求

python：3.10或更高
谷歌云项目：启用了工作区API
OAuth 2.0凭据：桌面应用程序类型
可选的: rclone 用于驱动器同步功能（4个工具）
可选的: 潘多克。用于Markdown到文档的转换
可选的: @美人鱼js/美人鱼cli 美人鱼图

故障排除

“未通过身份验证”错误

跑 workspace setup 通过以下方式进行身份验证或检查状态 workspace doctor.

令牌刷新失败

删除 ~/.gworkspace-mcp/tokens.json 然后跑 workspace setup 再一次。

缺少rclone工具

基于4个rclone的工具(list_drive_contents, download_drive_folder, upload_to_drive, sync_drive_folder)需要安装rclone。从以下位置安装 rclone.org.

Claude Desktop看不到工具

确保配置文件路径适合您的操作系统
配置更改后重新启动Claude Desktop
检查 workspace mcp 运行无错误

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
进行更改
运行测试和梳理
提交拉取请求

链接

仓库: https://github.com/masapasa/google-workspace-mcp
问题: https://github.com/masapasa/google-workspace-mcp/issues
PyPI: https://pypi.org/project/gworkspace-mcp/

致谢

提取自克劳德mpm -具有MCP服务器集成的多代理项目经理。