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 时可立即运行，无需手动安装，但你必须配置 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 项目

配置

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 管道
• ✅ 不会将机密信息存储在版本控制系统中
• ✅ 便于凭证轮换

环境配置

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

服务器配置

可使用环境变量自定义服务器的基本 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 设置 → 开发者 → 编辑配置
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • 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)

📁 Google Drive (drive_tools.py)

📧 Gmail (gmail_tools.py)

📝 Google Docs (docs_tools.py)

📊 Google Sheets (sheets_tools.py)

🖼️ Google Slides (slides_tools.py)

📝 Google Forms (forms_tools.py)

✓ Google Tasks (tasks_tools.py)

💬 Google Chat (chat_tools.py)

🛠️ 开发

项目结构

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() 适用于复杂工具。

🔧 技术细节

这是一个生产就绪的 MCP 服务器，将所有主要的 Google Workspace 服务与 AI 助手集成。使用 FastMCP 构建以实现最佳性能，具备高级认证处理、服务缓存和简化的开发模式。

🔒 安全

• 凭证管理：切勿将 client_secret.json 或 .credentials/ 目录提交到版本控制中。
• OAuth 回调：开发环境使用 http://localhost:8000/oauth2callback（需要 OAUTHLIB_INSECURE_TRANSPORT=1）。
• 传输感知回调：标准输入输出模式仅为 OAuth 启动一个最小的 HTTP 服务器，确保在所有模式下回调都能正常工作。
• 生产环境：回调 URI 使用 HTTPS 并进行相应配置。
• 网络暴露：通过网络使用 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 上提供你的 Google Workspace MCP 服务（假设端口 8000 上的服务已启动）。

3. 配置 Open WebUI

1. 导航到你的 Open WebUI 设置。
2. 转到 "连接" → "工具"。
3. 点击 "添加工具"。
4. 输入 服务器 URL：http://localhost:8001/google_workspace（与 config.json 中的 mcpo 基本 URL 和服务器名称匹配）。
5. 若你在 mcpo 中使用了 --api-key，请将其作为 API 密钥输入。
6. 保存配置。

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

📄 许可证

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