观看实际演示：

概述

Workspace MCP 是集成所有主要 Google Workspace 服务与 AI 助手的最完整 MCP 服务器。它既支持单用户操作，也支持通过 OAuth 2.1 进行多用户认证，是自定义应用程序的强大后端。基于 FastMCP 构建，具有卓越性能、先进的认证处理、服务缓存和精简的开发模式。整个工具集均可用于命令行界面，支持本地和远程实例。

简化设置：现采用 Google Desktop OAuth 客户端——无需配置重定向 URI 或端口！

特性

12 项服务 — Gmail · 云端硬盘 · 日历 · 文档 · 表格 · 幻灯片 · 表单 · 聊天 · Apps Script · 任务 · 联系人 · 搜索

快速入门

设置凭据 → 选择启动命令 → 连接客户端

# 1. 凭据
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."

# 2. 启动 — 选择层级
uvx workspace-mcp --tool-tier core       # 基础工具
uvx workspace-mcp --tool-tier extended   # 基础 + 管理操作
uvx workspace-mcp --tool-tier complete   # 全部

# 或者选择性地运行特定服务
uv run main.py --tools gmail drive calendar

_{凭据设置 → · 所有启动选项 → · 层级详情 →}

一键安装 Claude Desktop

.dxt 包含服务器、依赖项和清单文件——下载后双击即可完成安装，无需终端操作或编辑 JSON 文件。

1. 下载 最新的 google_workspace_mcp.dxt 文件，访问 Releases
2. 安装 — 双击该文件，Claude Desktop 会提示您进行安装
3. 配置 — 进入设置 → 扩展程序 → Google Workspace MCP，粘贴您的 OAuth 凭据
4. 使用 — 打开一个新的 Claude 对话，即可调用任何 Google Workspace 工具

先决条件

Python 3.10+ · uv/uvx · Google Cloud 项目 并具备 OAuth 2.0 凭据

配置

Google 自定义搜索设置

programmablesearchengine.google.com
/controlpanel/create

→ 配置特定站点或整个网页
→ 记下您的引擎 ID (cx)

developers.google.com
/custom-search/v1/overview

→ 创建或选择项目
→ 启用自定义搜索 API
→ 创建凭据（API 密钥）

export GOOGLE_PSE_API_KEY=\
  "your-api-key"
export GOOGLE_PSE_ENGINE_ID=\
  "your-engine-id"

启动服务器

📌 传输模式指南：对于所有现代 MCP 客户端，包括 Claude Code、VS Code MCP 和 MCP Inspector，请使用 流式 HTTP 模式（--transport streamable-http）。Stdio 模式仅适用于不完全支持 MCP 规范的客户端。

uv run main.py

uv run main.py \
  --transport streamable-http

uv run main.py \
  --single-user

# 只加载特定服务
uv run main.py --tools gmail drive calendar
uv run main.py --tools sheets docs

# 结合其他标志
uv run main.py --single-user --tools gmail

# 请求只读权限范围，并禁用写入工具
uv run main.py --read-only

# 结合特定工具或层级
uv run main.py --tools gmail drive --read-only
uv run main.py --tool-tier core --read-only

# 按服务设置权限级别
uv run main.py --permissions gmail:organize drive:readonly

# 将权限与层级筛选结合
uv run main.py --permissions gmail:send drive:full --tool-tier core

uv run main.py --tool-tier core      # ● 仅核心工具
uv run main.py --tool-tier extended  # ◐ 核心工具 + 其他
uv run main.py --tool-tier complete  # ○ 所有可用工具

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

# 通过环境变量选择工具
docker run -e TOOL_TIER=core workspace-mcp
docker run -e TOOLS="gmail drive calendar" workspace-mcp

CLI

workspace-cli 命令会列出工具并调用正在运行的服务器上的这些工具——它采用加密且基于磁盘的 OAuth 令牌缓存，因此您只需进行一次身份验证。首次运行时，它会打开浏览器以获取 Google 同意；后续运行则会自动重用已缓存的令牌。

令牌以加密形式存储在 ~/.workspace-mcp/cli-tokens/ 中，使用在 ~/.workspace-mcp/.cli-encryption-key 自动生成的 Fernet 密钥进行加密。

uv run workspace-cli list
uv run workspace-cli --url https://custom.server/mcp list

# 或者，如果已全局安装：
workspace-cli list
workspace-cli --url https://custom.server/mcp list

uv run workspace-cli call search_gmail_messages \
  query="is:unread" max_results=5

fastmcp inspect fastmcp_server.py                        # 打印工具、资源、提示
fastmcp install claude-code fastmcp_server.py             # 一键式客户端设置
fastmcp install cursor fastmcp_server.py
fastmcp discover                                          # 查找在编辑器中配置的服务器

工具层级

该服务器将工具组织成三个递进的层级，以简化部署。请根据您的使用需求和 API 配额要求选择合适的层级。

使用示例

# 基本层级选择
uv run main.py --tool-tier core                            # 仅启动基本工具
uv run main.py --tool-tier extended                        # 扩展到包含管理功能
uv run main.py --tool-tier complete                        # 启用所有可用功能

# 结合层级选择按需加载特定服务
uv run main.py --tools gmail drive --tool-tier core        # 为特定服务启用核心工具
uv run main.py --tools gmail --tool-tier extended          # 仅启用 Gmail 的扩展功能
uv run main.py --tools docs sheets --tool-tier complete    # 全面访问 Docs 和 Sheets

# 将层级选择与细粒度权限级别结合使用
uv run main.py --permissions gmail:organize drive:full --tool-tier core

📋 凭证配置

export GOOGLE_OAUTH_CLIENT_ID=\
  "your-client-id"
export GOOGLE_OAUTH_CLIENT_SECRET=\
  "your-secret"

# 下载并放置于项目根目录
client_secret.json

# 或指定自定义路径
export GOOGLE_CLIENT_SECRET_PATH=\
  /path/to/secret.json

cp .env.oauth21 .env
# 编辑 .env 文件填写凭证

🧰 可用工具

注意：所有工具均支持通过 @require_google_service() 装饰器实现自动身份验证，并具备 30 分钟的服务缓存机制。

📅 Google 日历 _{calendar_tools.py}

📁 Google 云端硬盘 _{drive_tools.py}

📧 Gmail _{gmail_tools.py}

attachments=[{"path": "/path/to/report.pdf"}]

attachments=[{
    "filename": "report.pdf",
    "content": "JVBERi0xLjQK...",  # base64 编码
    "mime_type": "application/pdf"   # 可选
}]

export WORKSPACE_ATTACHMENT_DIR="/path/to/custom/dir"

📝 Google 文档 _{docs_tools.py}

📊 Google 表格 _{sheets_tools.py}

🖼️ Google 幻灯片 _{slides_tools.py}

📋 Google 表单 _{forms_tools.py}

✓ Google 任务 _{tasks_tools.py}

👤 Google 联系人 _{contacts_tools.py}

💬 Google Chat _{chat_tools.py}

🔍 Google 自定义搜索 _{search_tools.py}

⚡ Google Apps Script _{apps_script_tools.py}

连接到 Claude Desktop

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

Stdio 模式（旧版 - 适用于不完全支持 MCP 的客户端）

⚠️ 重要提示: Stdio 模式是针对那些未正确实现带有 OAuth 2.1 和可流式传输 HTTP 支持的 MCP 规范的客户端的 遗留回退方案。Claude Code 及其他现代 MCP 客户端应使用可流式传输 HTTP 模式 (--transport streamable-http)，以实现正确的 OAuth 流程和多用户支持。

通常情况下，您应该使用 Claude Desktop 的一键 DXT 安装包。如果您因某种原因无法使用，则可以通过 claude_desktop_config.json 手动配置。

手动 Claude 配置（替代方案）

{
  "mcpServers": {
    "google_workspace": {
      "command": "uvx",
      "args": ["workspace-mcp"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "您的客户端 ID",
        "GOOGLE_OAUTH_CLIENT_SECRET": "您的密钥",
        "OAUTHLIB_INSECURE_TRANSPORT": "1"
      }
    }
  }
}

连接到 LM Studio

在 LM Studio 中添加一个新的 MCP 服务器（设置 → MCP 服务器），使用相同的 JSON 格式：

{
  "mcpServers": {
    "google_workspace": {
      "command": "uvx",
      "args": ["workspace-mcp"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "您的客户端 ID",
        "GOOGLE_OAUTH_CLIENT_SECRET": "您的密钥",
        "OAUTHLIB_INSECURE_TRANSPORT": "1",
      }
    }
  }
}

2. 高级 / 跨平台安装

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

即时 CLI (uvx)

# 需要 Python 3.10+ 和 uvx
# 首先设置凭据（参见上方的凭据配置）
uvx workspace-mcp --tool-tier core  # 或 --tools gmail drive calendar

本地开发设置

# 安装进行代码检查、测试和发布工具所需的全部内容
uv sync --group dev

# 运行与 git hooks 自动调用的相同 linter
uv run ruff check .

# 执行完整的测试套件（异步 fixture 需要 pytest-asyncio）
uv run pytest

OAuth 2.1 支持（多用户 Bearer 令牌认证）

服务器包含用于承载令牌认证的 OAuth 2.1 支持，可实现多用户会话管理。OAuth 2.1 会自动复用您现有的 GOOGLE_OAUTH_CLIENT_ID 和 GOOGLE_OAUTH_CLIENT_SECRET 凭证——无需额外配置！

何时使用 OAuth 2.1：

• 多个用户访问同一个 MCP 服务器实例
• 需要使用承载令牌认证而非传递用户邮箱
• 在 MCP 服务器之上构建 Web 应用程序或 API
• 生产环境需要安全的会话管理
• 基于浏览器的客户端需要 CORS 支持

⚠️ 重要提示：OAuth 2.1 与单用户模式互斥

OAuth 2.1 模式（MCP_ENABLE_OAUTH21=true）不能与 --single-user 标志同时使用：

• 单用户模式：适用于在工具调用中传递用户邮箱的旧版客户端
• OAuth 2.1 模式：适用于使用承载令牌认证的现代多用户场景

请仅选择一种认证方式；同时使用两者会导致启动错误。

启用 OAuth 2.1： 要启用 OAuth 2.1，请将 MCP_ENABLE_OAUTH21 环境变量设置为 true。

# OAuth 2.1 需要 HTTP 传输模式
export MCP_ENABLE_OAUTH21=true
uv run main.py --transport streamable-http

如果未将 MCP_ENABLE_OAUTH21 设置为 true，服务器将使用传统认证方式，这适用于不支持 OAuth 2.1 的客户端。

无状态模式（适合容器化环境）

服务器支持无状态模式，专为应避免文件系统写入的容器化环境设计：

启用无状态模式：

# 无状态模式要求启用 OAuth 2.1
export MCP_ENABLE_OAUTH21=true
export WORKSPACE_MCP_STATELESS_MODE=true
uv run main.py --transport streamable-http

主要特性：

• 不写入文件系统：凭据绝不会写入磁盘
• 无调试日志：完全禁用基于文件的日志记录
• 仅内存会话：所有令牌通过 OAuth 2.1 会话存储保存在内存中
• 适合容器：非常适合 Docker、Kubernetes 和无服务器部署
• 每请求令牌：每个请求必须包含有效的 Bearer 令牌

要求：

• 必须与 MCP_ENABLE_OAUTH21=true 一起使用
• 不兼容单用户模式
• 客户端必须自行完成 OAuth 流程，并在每次请求中发送有效令牌

此模式非常适合：

• 无法使用持久化存储的云部署
• 需要严格隔离的多租户环境
• 具有只读文件系统的容器化应用
• 无服务器函数和临时计算环境

MCP Inspector：使用桌面 OAuth 客户端时无需额外配置。 Claude Code：使用桌面 OAuth 客户端时无需额外配置。

OAuth 代理存储后端

服务器支持可插拔的存储后端，用于通过 FastMCP 2.13.0+ 管理 OAuth 代理的状态。请根据您的部署需求选择合适的后端。

可用后端：

配置：

# 内存存储（速度快，无持久性）
export WORKSPACE_MCP_OAUTH_PROXY_STORAGE_BACKEND=memory

# 磁盘存储（重启后仍保留数据）
export WORKSPACE_MCP_OAUTH_PROXY_STORAGE_BACKEND=disk
export WORKSPACE_MCP_OAUTH_PROXY_DISK_DIRECTORY=~/.fastmcp/oauth-proxy

# Valkey/Redis 存储（分布式，支持多服务器）
export WORKSPACE_MCP_OAUTH_PROXY_STORAGE_BACKEND=valkey
export WORKSPACE_MCP_OAUTH_PROXY_VALKEY_HOST=redis.example.com
export WORKSPACE_MCP_OAUTH_PROXY_VALKEY_PORT=6379

磁盘支持需要在源码安装时指定 workspace-mcp[disk]（或 py-key-value-aio[disk]）。 官方 Docker 镜像默认包含 disk 附加组件。 Valkey 支持是可选的。仅当启用 Valkey 后端时，才需安装 workspace-mcp[valkey]（或 py-key-value-aio[valkey]）。 Windows：从源码构建 valkey-glide 需要支持 C11 的 MSVC C++ 编译工具。如果出现 aws-lc-sys C11 错误，请设置 CFLAGS=/std:c11。

外部 OAuth 2.1 提供者模式

服务器支持外部 OAuth 2.1 提供者模式，适用于由外部系统负责认证的场景。在此模式下，MCP 服务器本身不管理 OAuth 流程，而是期望在工具调用的 Authorization 头中接收到有效的承载令牌。

启用外部 OAuth 2.1 提供者模式：

# 外部 OAuth 提供者模式需要启用 OAuth 2.1
export MCP_ENABLE_OAUTH21=true
export EXTERNAL_OAUTH21_PROVIDER=true
uv run main.py --transport streamable-http

工作原理：

• 协议级认证已启用：所有 MCP 请求（包括 initialize 和 tools/list）都需要有效的 Bearer 令牌，遵循标准的 OAuth 2.1 流程。未通过认证的请求将收到 401 响应，其中包含指向 Google 授权服务器的资源元数据。
• 外部 OAuth 流程：您的外部系统负责处理 OAuth 流程并获取 Google 访问令牌（ya29.*）。
• 令牌验证：服务器通过调用 Google 的 userinfo API 来验证 Bearer 令牌。
• 多用户支持：每个请求都根据其 Bearer 令牌独立进行认证。
• 资源元数据发现：服务器会提供 /.well-known/oauth-protected-resource（RFC 9728），声明 Google 为授权服务器，并列出所需的范围。

关键特性：

• 无本地 OAuth 流程：服务器不提供 /authorize、/token 或 /register 端点——仅提供资源元数据。
• 仅支持 Bearer 令牌：所有认证均通过 Authorization: Bearer <token> 头部完成。
• 设计上无状态：与 WORKSPACE_MCP_STATELESS_MODE=true 无缝兼容。
• 外部身份提供商：可与您现有的认证基础设施集成。

要求：

• 必须与 MCP_ENABLE_OAUTH21=true 一起使用。
• 仍需 OAuth 凭证用于令牌验证（GOOGLE_OAUTH_CLIENT_ID、GOOGLE_OAUTH_CLIENT_SECRET）。
• 外部系统必须获取有效的 Google OAuth 访问令牌（ya29.*）。
• 每个工具调用请求都必须包含有效的 Bearer 令牌。

使用场景：

• 集成现有认证系统。
• 由您的应用程序管理的自定义 OAuth 流程。
• 在上游处理认证的 API 网关。
• 具有集中式认证的多租户 SaaS 应用程序。
• 自带 OAuth 实现的移动或 Web 应用程序。

VS Code MCP 客户端支持

✅ 推荐：VS Code MCP 扩展完全支持完整的 MCP 规范。请务必使用 HTTP 传输模式以实现正确的 OAuth 2.1 认证。

{
    "servers": {
        "google-workspace": {
            "url": "http://localhost:8000/mcp/",
            "type": "http"
        }
    }
}

Claude Code MCP 客户端支持

✅ 推荐：Claude Code 是一款现代的 MCP 客户端，能够正确支持完整的 MCP 规范。为了实现正确的 OAuth 2.1 认证和多用户支持，始终建议使用 HTTP 传输模式。

# 首先以 HTTP 模式启动服务器
uv run main.py --transport streamable-http

# 然后添加到 Claude Code
claude mcp add --transport http workspace-mcp http://localhost:8000/mcp

反向代理设置

如果您将 MCP 服务器部署在反向代理（nginx、Apache、Cloudflare 等）之后，您有两种配置选项：

问题：当位于反向代理之后时，服务器会使用内部端口构建 OAuth URL（例如 http://localhost:8000），但外部客户端需要的是公共 URL（例如 https://your-domain.com）。

解决方案 1：为所有 OAuth 端点设置 WORKSPACE_EXTERNAL_URL：

# 此配置会使所有 OAuth 端点使用您的外部 URL
export WORKSPACE_EXTERNAL_URL="https://your-domain.com"

解决方案 2：仅为回调设置 GOOGLE_OAUTH_REDIRECT_URI：

# 这仅会覆盖 OAuth 回调 URL
export GOOGLE_OAUTH_REDIRECT_URI="https://your-domain.com/oauth2callback"

此外，您还可以选择以下配置： | OAUTH_CUSTOM_REDIRECT_URIS (可选) | 逗号分隔的额外重定向 URI 列表 | | OAUTH_ALLOWED_ORIGINS (可选) | 逗号分隔的额外 CORS 域列表 |

重要提示：

• 当所有 OAuth 端点都应使用外部 URL 时，请使用 WORKSPACE_EXTERNAL_URL（推荐用于反向代理设置）。
• 当只需覆盖回调 URL 时，请使用 GOOGLE_OAUTH_REDIRECT_URI。
• 重定向 URI 必须与 Google Cloud 控制台中配置的完全一致。
• 您的反向代理必须将 OAuth 相关请求（/oauth2callback、/oauth2/*、/.well-known/*）转发至 MCP 服务器。

# 首先配置凭据（参见凭据配置部分）

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

# 按工具层级启动（推荐给大多数用户）
uvx workspace-mcp --tool-tier core      # 核心工具
uvx workspace-mcp --tool-tier extended  # 核心工具 + 高级功能
uvx workspace-mcp --tool-tier complete  # 所有工具

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

需要 Python 3.10+ 和 uvx。该软件包可在 PyPI 上找到。

开发安装

用于开发或自定义：

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

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

🔧 开发者设置 JSON _{^{← 适用于贡献者及自定义}}

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

</details。

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

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

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

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

首次认证

服务器使用 Google Desktop OAuth 进行简化认证：

• 无需重定向 URI：桌面 OAuth 客户端无需复杂的回调 URL 即可完成认证
• 自动流程：服务器会透明地管理整个 OAuth 流程
• 传输无关性：无论是在 stdio 模式还是 HTTP 模式下都能无缝工作

调用工具时：

1. 服务器返回授权 URL
2. 在浏览器中打开该 URL 并进行授权
3. Google 提供授权码
4. 按提示粘贴授权码（或由系统自动处理）
5. 服务器完成认证并重新尝试您的请求

---

◆ 开发

项目结构

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):
    """工具描述"""
    # service 会自动注入并缓存
    result = service.files().list().execute()
    return result  # 返回原生 Python 对象

架构亮点

• 服务缓存：30 分钟 TTL 降低认证开销
• 权限范围管理：集中于 SCOPE_GROUPS，便于维护
• 错误处理：使用原生异常，而非手动构造错误
• 多服务支持：@require_multiple_services() 用于复杂工具

凭证存储系统

服务器包含一个抽象的凭证存储 API 和一个默认后端，用于管理 Google OAuth 凭证，并支持多种存储后端：

特性：

• 抽象接口：CredentialStore 基类定义了标准操作（获取、存储、删除、列出用户）
• 本地文件存储：LocalDirectoryCredentialStore 实现将凭证以 JSON 文件形式存储
• 可配置存储位置：环境变量 GOOGLE_MCP_CREDENTIALS_DIR 可设置存储路径
• 多用户支持：可为多个 Google 账号存储和管理凭证
• 自动创建目录：如果存储目录不存在，则会自动创建

配置：

# 可选：设置自定义凭证目录
export GOOGLE_MCP_CREDENTIALS_DIR="/path/to/credentials"

# 默认位置（若未设置 GOOGLE_MCP_CREDENTIALS_DIR）：
# - ~/.google_workspace_mcp/credentials（若主目录可访问）
# - ./.credentials（备用）

使用示例：

from auth.credential_store import get_credential_store

# 获取全局凭证存储实例
store = get_credential_store()

# 存储某用户的凭证
store.store_credential("user@example.com", credentials)

# 获取凭证
creds = store.get_credential("user@example.com")

# 列出所有已存储凭证的用户
users = store.list_users()

凭证存储会自动处理凭证序列化、过期解析，并为存储操作提供错误处理。

---

⊠ 安全

• 提示注入：此 MCP 服务器具备检索您的电子邮件、日历事件和云端硬盘文件的能力。这些邮件、事件和文件可能包含提示注入——即隐藏的白色文本，指示其将您的邮件转发至其他地址。请务必谨慎操作，通常仅应将可信数据连接到 LLM！
• 凭证安全：切勿将 .env、client_secret.json 或 .credentials/ 目录提交到版本控制系统！
• OAuth 回调：开发时使用 http://localhost:8000/oauth2callback（需设置 OAUTHLIB_INSECURE_TRANSPORT=1）
• 传输感知回调：在 stdio 模式下，仅启动一个最小化的 HTTP 服务器用于 OAuth，确保回调在所有模式下均能正常工作。
• 生产环境：请使用 HTTPS 和 OAuth 2.1，并相应配置。
• 权限范围最小化：工具仅请求必要的权限。
• 本地文件访问控制：读取本地文件的工具（例如附件、file:// 上传）默认仅允许访问用户的主目录。可通过 ALLOWED_FILE_DIRS 环境变量覆盖此限制：

  # 以冒号分隔的目录列表（Windows 使用分号），指定允许读取本地文件的目录
  export ALLOWED_FILE_DIRS="/home/user/documents:/data/shared"
  

  不论白名单如何，对敏感路径（.env、.ssh/、.aws/、/etc/shadow、凭证文件等）的访问始终被禁止。

---

---

≡ 许可证

MIT 许可证——详情请参阅 LICENSE 文件。

---

验证：

Google Workspace MCP 快速上手指南

Google Workspace MCP 是一个功能完备的模型上下文协议（MCP）服务器，允许 AI 助手通过自然语言全面控制 Google 全家桶（Gmail、Drive、日历、文档、表格等）。它支持单用户本地运行及多用户 OAuth 2.1 部署。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统：Linux, macOS, 或 Windows
• Python 版本：Python 3.10 或更高版本
• 包管理器：推荐安装 uv (高性能 Python 包管理工具)

  # 安装 uv (Linux/macOS)
  curl -LsSf https://astral.sh/uv/install.sh | sh
  
  # 安装 uv (Windows PowerShell)
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  

• Google Cloud 项目：需要拥有一个 Google Cloud 项目并启用相关 API。

安装与配置步骤

1. 配置 Google Cloud 凭证

这是最关键的一步，用于授权 MCP 访问你的 Google 服务。

1. 创建项目与凭证：

   • 访问 Google Cloud Console 创建新项目。
   • 进入 API 和服务 > 凭据 > 创建凭据 > OAuth 客户端 ID。
   • 应用类型选择：桌面应用 (Desktop Application)。
   • 注意：选择桌面应用无需配置重定向 URI，简化了设置。
   • 下载生成的 client_secret.json 或记录 Client ID 和 Client Secret。

2. 启用必要的 API： 在 API 和服务 > 库 中，搜索并启用你需要的服务 API，例如：

   • Gmail API, Google Drive API, Google Calendar API
   • Google Docs API, Sheets API, Slides API
   • Tasks API, People API (Contacts), Chat API 等。

3. 设置环境变量： 在终端中导出你的凭证信息（开发模式下需允许非安全传输）：

   export GOOGLE_OAUTH_CLIENT_ID="你的_CLIENT_ID"
   export GOOGLE_OAUTH_CLIENT_SECRET="你的_CLIENT_SECRET"
   
   # 开发环境必需：允许 http 重定向
   export OAUTHLIB_INSECURE_TRANSPORT=1
   

2. 安装与启动服务器

推荐使用 uvx 直接运行，无需手动创建虚拟环境。你可以根据需求选择不同的工具集层级：

# 选项 A: 启动核心工具集 (Gmail, Drive, Calendar 等基础功能)
uvx workspace-mcp --tool-tier core

# 选项 B: 启动扩展工具集 (核心 + 管理操作)
uvx workspace-mcp --tool-tier extended

# 选项 C: 启动完整工具集 (包含所有支持的服务，如 Forms, Chat, Apps Script)
uvx workspace-mcp --tool-tier complete

# 选项 D: 仅启动特定服务 (例如只启用 Gmail 和 Drive)
uv run main.py --tools gmail drive

首次运行时，终端会输出一个链接，点击该链接并在浏览器中完成 Google 账号授权，授权后凭证将自动保存。

3. 连接 AI 客户端 (以 Claude Desktop 为例)

方法一：一键安装 (推荐)

1. 从项目的 Releases 页面 下载最新的 google_workspace_mcp.dxt 文件。
2. 双击该文件，Claude Desktop 会自动提示安装。
3. 在 Claude Desktop 的 Settings > Extensions 中找到 Google Workspace MCP，粘贴你的 OAuth Client ID 和 Secret。
4. 重启 Claude Desktop 即可使用。

方法二：手动配置 (stdio 模式)

如果你使用的是其他支持 MCP 的客户端（如 VS Code MCP 插件），请在配置文件中添加以下内容：

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": ["workspace-mcp", "--tool-tier", "complete"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "你的_CLIENT_ID",
        "GOOGLE_OAUTH_CLIENT_SECRET": "你的_CLIENT_SECRET",
        "OAUTHLIB_INSECURE_TRANSPORT": "1"
      }
    }
  }
}

基本使用示例

配置完成后，你可以在支持的 AI 助手（如 Claude）中直接使用自然语言操作 Google 服务。

示例对话：

用户: "帮我查一下明天上午 10 点有没有空，如果有，创建一个名为'项目评审'的会议邀请，并把我 Drive 里最新的'项目计划.docx'附件加进去。"

AI (调用 MCP 工具):

1. 调用 calendar_list_events 检查明天上午时段。
2. 调用 drive_search_files 查找 "项目计划.docx"。
3. 调用 calendar_create_event 创建会议并附加文件链接。

AI 回复: "已为您安排明天上午 10 点的'项目评审'会议，并附上了最新的 project_plan.docx 文档。"

用户: "把上周收到的所有来自老板的邮件标记为重要，并总结主要内容。"

AI (调用 MCP 工具):

1. 调用 gmail_search_messages 筛选发件人和时间。
2. 调用 gmail_modify_labels 添加 "IMPORTANT" 标签。
3. 读取邮件内容并生成总结。

现在，你已经成功部署并开始使用 Google Workspace MCP！