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 ()

📁 Google Drive ()

📧 Gmail ()

📝 Google Docs ()

📊 Google Sheets ()

🖼️ Google Slides ()

📝 Google Forms ()

✓ Google Tasks ()

💬 Google Chat ()

🔧 技术细节

项目结构

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 文件。