google_workspace_mcp

🚀 Google Workspace MCP Server

这是功能最齐全的 Google Workspace MCP 服务器，现在支持一键安装 Claude。借助所有 MCP 客户端、AI 助手和开发工具，可对 Google Calendar、Drive、Gmail、Docs、Sheets、Slides、Forms、Tasks 和 Chat 进行全面的自然语言控制。

支持所有免费 Google 账户（Gmail、Docs、Drive 等）和 Google Workspace 计划（Starter、Standard、Plus、Enterprise、Non Profit 等）及其扩展应用选项，如 Chat 和 Spaces。

查看实际运行效果

关于 AI 增强文档的简要说明

🚀 快速开始

1. 一键安装 Claude Desktop（推荐）

1. 下载：从“Releases”页面获取最新的 google_workspace_mcp.dxt 文件。
2. 安装：双击该文件，Claude Desktop 会打开并提示你进行“安装”操作。
3. 配置：在 Claude Desktop 中，依次点击 Settings → Extensions → Google Workspace MCP，粘贴你的 Google OAuth 凭证。
4. 使用：开启一个新的 Claude 聊天会话，即可调用任何 Google Workspace 工具。

⚠️ 重要提示

为何使用 DXT 文件？桌面扩展（.dxt）将服务器、依赖项和清单文件打包在一起，用户只需一键操作，就能从下载过渡到使用 MCP，无需使用终端、编辑 JSON 文件，也不会出现版本冲突问题。

所需配置

2. 高级/跨平台安装

如果你正在进行开发、将其部署到服务器，或者使用其他支持 MCP 的客户端，请继续阅读。

即时命令行安装（uvx）

# 需要 Python 3.11+ 和 uvx
export GOOGLE_OAUTH_CLIENT_ID="xxx"
export GOOGLE_OAUTH_CLIENT_SECRET="yyy"
uvx workspace-mcp --tools gmail drive calendar

⚠️ 重要提示

使用 uvx 时，可立即运行而无需手动安装，但你必须配置 Google OAuth 凭证。你可以使用环境变量（推荐用于生产环境），或者设置 GOOGLE_CLIENT_SECRET_PATH（或旧版的 GOOGLE_CLIENT_SECRETS）环境变量，指向你的 client_secret.json 文件。

# 通过环境变量设置 OAuth 凭证（推荐）
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"

# 启动包含所有 Google Workspace 工具的服务器
uvx workspace-mcp

# 仅启动特定工具
uvx workspace-mcp --tools gmail drive calendar tasks

# 以 HTTP 模式启动进行调试
uvx workspace-mcp --transport streamable-http

需要 Python 3.11+ 和 uvx。该软件包可在 PyPI 上获取。

开发环境安装

若要进行开发或定制：

git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp
uv run main.py

前提条件

• Python 3.11+
• uvx（用于即时安装）或 uv（用于开发）
• 具有 OAuth 2.0 凭证的 Google Cloud 项目

配置

1. Google Cloud 设置：

   • 在 Google Cloud Console 中创建 OAuth 2.0 凭证（Web 应用程序）。

   • 启用以下 API：Calendar、Drive、Gmail、Docs、Sheets、Slides、Forms、Tasks、Chat。

   • 添加重定向 URI：http://localhost:8000/oauth2callback。

   • 使用以下方法之一配置凭证：

     选项 A：环境变量（推荐用于生产环境）

     export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
     export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
     export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"  # 可选
     

     选项 B：基于文件（传统方式）

     • 将凭证下载为 client_secret.json 文件，放置在项目根目录下。
     • 若要使用其他位置的文件，可设置 GOOGLE_CLIENT_SECRET_PATH（或旧版的 GOOGLE_CLIENT_SECRETS）环境变量，指定文件路径。

   凭证加载优先级：

   1. 环境变量（GOOGLE_OAUTH_CLIENT_ID、GOOGLE_OAUTH_CLIENT_SECRET）
   2. GOOGLE_CLIENT_SECRET_PATH 或 GOOGLE_CLIENT_SECRETS 环境变量指定的文件
   3. 默认文件（项目根目录下的 client_secret.json）

   💡 使用建议

   为何推荐使用环境变量？

   • ✅ 适用于容器化部署（Docker、Kubernetes）
   • ✅ 适用于云平台（Heroku、Railway 等）
   • ✅ 适用于 CI/CD 管道
   • ✅ 避免将机密信息存储在版本控制系统中
   • ✅ 便于凭证轮换

2. 环境变量配置：

   export OAUTHLIB_INSECURE_TRANSPORT=1  # 仅用于开发环境
   export USER_GOOGLE_EMAIL=your.email@gmail.com  # 可选：认证的默认电子邮件 - 用于单用户设置，使用此选项后，在魔法认证的系统提示中无需设置电子邮件
   

3. 服务器配置： 可以使用环境变量自定义服务器的基本 URL 和端口：

   • WORKSPACE_MCP_BASE_URI：设置服务器的基本 URI（默认：http://localhost）。如果未设置 GOOGLE_OAUTH_REDIRECT_URI，此设置将影响用于构建默认 OAUTH_REDIRECT_URI 的 server_url。
   • WORKSPACE_MCP_PORT：设置服务器监听的端口（默认：8000）。此设置将影响 server_url、端口和 OAUTH_REDIRECT_URI。
   • USER_GOOGLE_EMAIL：可选的认证流程默认电子邮件。如果设置了该值，大语言模型在调用 start_google_auth 时无需指定你的电子邮件。
   • GOOGLE_OAUTH_REDIRECT_URI：专门用于覆盖 OAuth 重定向的设置，必须包含完整地址（必要时需包含端口）。仅在非常特殊的情况下推荐使用此设置，若要将 OAuth 重定向与 MCP 分开运行，可使用此选项。

启动服务器

# 默认（适用于 MCP 客户端的标准输入输出模式）
uv run main.py

# HTTP 模式（用于 Web 界面和调试）
uv run main.py --transport streamable-http

# 单用户模式（简化认证流程）
uv run main.py --single-user

# 选择性工具注册（仅注册特定工具）
uv run main.py --tools gmail drive calendar tasks
uv run main.py --tools sheets docs
uv run main.py --single-user --tools gmail  # 可与其他标志组合使用

# Docker 部署
docker build -t workspace-mcp .
docker run -p 8000:8000 -v $(pwd):/app workspace-mcp --transport streamable-http

--tools 标志可用的工具：gmail、drive、calendar、docs、sheets、forms、tasks、chat

连接到 Claude Desktop

服务器支持两种传输模式：

标准输入输出模式（默认 - 推荐用于 Claude Desktop）

引导式设置（若未使用 DXT，推荐此方式）

python install_claude.py

此脚本会自动执行以下操作：

• 提示你输入 Google OAuth 凭证（客户端 ID 和密钥）
• 在正确的位置创建 Claude Desktop 配置文件
• 设置所有必要的环境变量
• 无需手动编辑文件！

运行脚本后，重启 Claude Desktop 即可开始使用。

手动配置 Claude（替代方法）

1. 打开 Claude Desktop 设置 → 开发者 → 编辑配置
   1. macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   2. Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 添加服务器配置：

   {
     "mcpServers": {
       "google_workspace": {
         "command": "uvx",
         "args": ["workspace-mcp"],
         "env": {
           "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
           "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
           "OAUTHLIB_INSECURE_TRANSPORT": "1"
         }
       }
     }
   }
   

获取 Google OAuth 凭证（如果你还没有）：

• 访问 Google Cloud Console
• 创建一个新项目，并启用以下 API：Calendar、Drive、Gmail、Docs、Sheets、Slides、Forms、Tasks、Chat
• 创建 OAuth 2.0 客户端 ID（Web 应用程序），并设置重定向 URI 为：http://localhost:8000/oauth2callback

开发环境安装（适用于贡献者）：

{
  "mcpServers": {
    "google_workspace": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/repo/google_workspace_mcp",
        "main.py"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTHLIB_INSECURE_TRANSPORT": "1"
      }
    }
  }
}

HTTP 模式（用于调试或 Web 界面）

如果你需要在 Claude Desktop 中使用 HTTP 模式：

{
  "mcpServers": {
    "google_workspace": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

⚠️ 重要提示

使用 HTTP 模式时，请确保使用 --transport streamable-http 启动服务器。

首次认证

服务器具备 支持传输感知的 OAuth 回调处理功能：

• 标准输入输出模式：自动在端口 8000 上启动一个最小化的 HTTP 服务器，用于处理 OAuth 回调。
• HTTP 模式：使用现有的 FastAPI 服务器处理 OAuth 回调。
• 统一的 OAuth 流程：两种模式均使用 http://localhost:8000/oauth2callback 以确保一致性。

调用工具时：

1. 服务器返回授权 URL。
2. 在浏览器中打开该 URL 并进行授权。
3. 服务器自动处理 OAuth 回调（两种模式均在端口 8000 上）。
4. 重试原始请求。

✨ 主要特性

• 🔐 高级 OAuth 2.0：安全的认证机制，具备自动令牌刷新、支持传输感知的回调处理、会话管理和集中式范围管理功能。
• 📅 Google Calendar：全面的日历管理，支持事件的创建、读取、更新和删除操作。
• 📁 Google Drive：文件操作，支持原生 Microsoft Office 格式（.docx、.xlsx）。
• 📧 Gmail：完整的电子邮件管理，具备搜索、发送和草稿功能。
• 📄 Google Docs：文档操作，包括内容提取、创建和评论管理。
• 📊 Google Sheets：全面的电子表格管理，支持灵活的单元格操作和评论管理。
• 🖼️ Google Slides：演示文稿管理，支持幻灯片的创建、更新、内容操作和评论管理。
• 📝 Google Forms：表单创建、检索、发布设置和响应管理。
• ✓ Google Tasks：完整的任务和任务列表管理，支持层次结构、截止日期和状态跟踪。
• 💬 Google Chat：空间管理和消息传递功能。
• 🔄 全传输支持：支持标准输入输出、可流式传输的 HTTP 和 Server-Sent Events（SSE），通过 mcpo 实现 OpenAPI 兼容性。
• ⚡ 高性能：服务缓存、线程安全的会话和 FastMCP 集成。
• 🧩 开发者友好：最少的样板代码、自动服务注入和集中式配置。

🧰 可用工具

⚠️ 重要提示

所有工具均支持通过 @require_google_service() 装饰器实现自动认证，并具备 30 分钟的服务缓存。

📅 Google Calendar (calendar_tools.py)

| 工具 | 描述 | |------|-------------| | list_calendars | 列出可访问的日历 | | get_events | 根据时间范围过滤检索事件 | | get_event | 通过 ID 获取单个事件的详细信息 | | create_event | 创建事件（全天或定时），可选择附加 Drive 文件 | | modify_event | 更新现有事件 | | delete_event | 删除事件 |

📁 Google Drive (drive_tools.py)

| 工具 | 描述 | |------|-------------| | search_drive_files | 使用查询语法搜索文件 | | get_drive_file_content | 读取文件内容（支持 Office 格式） | | list_drive_items | 列出文件夹内容 | | create_drive_file | 创建新文件或从公共 URL 获取内容 |

📧 Gmail (gmail_tools.py)

| 工具 | 描述 | |------|-------------| | search_gmail_messages | 使用 Gmail 操作符进行搜索 | | get_gmail_message_content | 获取邮件内容 | | send_gmail_message | 发送电子邮件 | | draft_gmail_message | 创建草稿 |

📝 Google Docs (docs_tools.py)

| 工具 | 描述 | |------|-------------| | search_docs | 按名称查找文档 | | get_doc_content | 提取文档文本 | | list_docs_in_folder | 列出文件夹中的文档 | | create_doc | 创建新文档 | | read_doc_comments | 读取所有评论和回复 | | create_doc_comment | 创建新评论 | | reply_to_comment | 回复现有评论 | | resolve_comment | 解决评论 |

📊 Google Sheets (sheets_tools.py)

| 工具 | 描述 | |------|-------------| | list_spreadsheets | 列出可访问的电子表格 | | get_spreadsheet_info | 获取电子表格元数据 | | read_sheet_values | 读取单元格范围的值 | | modify_sheet_values | 写入、更新或清除单元格内容 | | create_spreadsheet | 创建新的电子表格 | | create_sheet | 在现有文件中添加工作表 | | read_sheet_comments | 读取所有评论和回复 | | create_sheet_comment | 创建新评论 | | reply_to_sheet_comment | 回复现有评论 | | resolve_sheet_comment | 解决评论 |

🖼️ Google Slides (slides_tools.py)

| 工具 | 描述 | |------|-------------| | create_presentation | 创建新的演示文稿 | | get_presentation | 获取演示文稿的详细信息 | | batch_update_presentation | 一次性应用多个更新操作 | | get_page | 获取特定幻灯片的信息 | | get_page_thumbnail | 生成幻灯片缩略图 | | read_presentation_comments | 读取所有评论和回复 | | create_presentation_comment | 创建新评论 | | reply_to_presentation_comment | 回复现有评论 | | resolve_presentation_comment | 解决评论 |

📝 Google Forms (forms_tools.py)

| 工具 | 描述 | |------|-------------| | create_form | 创建新表单，可设置标题和描述 | | get_form | 获取表单的详细信息、问题和 URL | | set_publish_settings | 配置表单模板和认证设置 | | get_form_response | 获取单个表单响应的详细信息 | | list_form_responses | 分页列出表单的所有响应 |

✓ Google Tasks (tasks_tools.py)

| 工具 | 描述 | |------|-------------| | list_task_lists | 分页列出所有任务列表 | | get_task_list | 获取特定任务列表的详细信息 | | create_task_list | 创建带有自定义标题的新任务列表 | | update_task_list | 修改现有任务列表的标题 | | delete_task_list | 删除任务列表及其包含的所有任务 | | list_tasks | 根据过滤选项列出特定列表中的任务 | | get_task | 获取特定任务的详细信息 | | create_task | 创建新任务，可设置标题、备注、截止日期和层次结构 | | update_task | 修改任务属性，包括标题、备注、状态和截止日期 | | delete_task | 从任务列表中删除任务 | | move_task | 在列表中重新定位任务或在不同列表之间移动任务 | | clear_completed_tasks | 隐藏列表中所有已完成的任务 |

💬 Google Chat (chat_tools.py)

| 工具 | 描述 | |------|-------------| | list_spaces | 列出聊天空间/房间 | | get_messages | 获取空间中的消息 | | send_message | 向空间发送消息 | | search_messages | 在聊天历史记录中进行搜索 |

🔧 技术细节

项目结构

google_workspace_mcp/
├── auth/              # 带有装饰器的认证系统
├── core/              # MCP 服务器和实用工具
├── g{service}/        # 特定服务的工具
├── main.py            # 服务器入口点
├── client_secret.json # OAuth 凭证（不提交到版本控制）
└── pyproject.toml     # 依赖项

添加新工具

from auth.service_decorator import require_google_service

@require_google_service("drive", "drive_read")  # 服务 + 范围组
async def your_new_tool(service, param1: str, param2: int = 10):
    """工具描述"""
    # 服务会自动注入并缓存
    result = service.files().list().execute()
    return result  # 返回原生 Python 对象

架构亮点

• 服务缓存：30 分钟的缓存过期时间（TTL），减少认证开销。
• 范围管理：集中在 SCOPE_GROUPS 中，便于维护。
• 错误处理：使用原生异常，而非手动构建错误信息。
• 多服务支持：@require_multiple_services() 装饰器适用于复杂工具。

🔒 安全说明

• 凭证管理：切勿将 client_secret.json 或 .credentials/ 目录提交到版本控制系统。
• OAuth 回调：开发环境使用 http://localhost:8000/oauth2callback（需要设置 OAUTHLIB_INSECURE_TRANSPORT=1）。
• 支持传输感知的回调：标准输入输出模式仅为 OAuth 启动一个最小化的 HTTP 服务器，确保在所有模式下回调功能正常工作。
• 生产环境：使用 HTTPS 作为回调 URI 并进行相应配置。
• 网络暴露：通过网络使用 mcpo 时，请考虑认证机制。
• 最小化权限范围：工具仅请求必要的权限。

🌐 与 Open WebUI 集成

若要在 Open WebUI 中使用此服务器作为工具提供者：

即时启动（无需配置）

只需复制并粘贴以下内容，设置好相应的值即可开始使用！

GOOGLE_OAUTH_CLIENT_ID="your_client_id" GOOGLE_OAUTH_CLIENT_SECRET="your_client_secret" uvx mcpo --port 8000 --api-key "top-secret" -- uvx workspace-mcp

手动配置步骤

1. 创建 MCPO 配置文件

创建一个名为 config.json 的文件，使用以下结构，让 mcpo 将可流式传输的 HTTP 端点作为 OpenAPI 规范工具提供：

{
  "mcpServers": {
    "google_workspace": {
      "type": "streamablehttp",
      "url": "http://localhost:8000/mcp"
    }
  }
}

2. 启动 MCPO 服务器

mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"

此命令将启动 mcpo 代理，在端口 8001 上提供你正在运行的（假设端口为 8000）Google Workspace MCP 服务。

3. 配置 Open WebUI

1. 导航到你的 Open WebUI 设置页面。
2. 进入 "Connections" → "Tools"。
3. 点击 "Add Tool"。
4. 输入 Server URL：http://localhost:8001/google_workspace（需与 config.json 中的 mcpo 基本 URL 和服务器名称匹配）。
5. 如果你在启动 mcpo 时使用了 --api-key，请在此处输入该 API 密钥。
6. 保存配置。

配置完成后，在 Open WebUI 中与模型交互时，即可使用 Google Workspace 工具。

📄 许可证

本项目采用 MIT 许可证，详细信息请参阅 LICENSE 文件。