Google Workspace MCP 服务器

谷歌工作区MCP服务器

通过所有MCP客户端、人工智能助手和开发工具，对谷歌日历、云端硬盘、Gmail、文档、表格、幻灯片、表单、任务和聊天进行完全自然语言控制。

功能最齐全的Google Workspace MCP服务器，现在支持Remote OAuth2.1多用户支持，一键安装Claude。

支持所有免费的谷歌帐户（Gmail、Docs、Drive等）和谷歌工作区计划（Starter、Standard、Plus、Enterprise、Non-Prefit），并提供聊天和共享空间等扩展应用程序选项。
对私有云实例感兴趣？ 这是可以安排的。

看看它在行动：

AI增强文档的快速插件

概述

一个生产就绪的MCP服务器，将所有主要的谷歌工作区服务与人工智能助手集成在一起。它通过OAuth 2.1支持单用户操作和多用户身份验证，使其成为定制应用程序的强大后端。采用FastMCP构建，可实现最佳性能，具有高级身份验证处理、服务缓存和简化的开发模式。

简化设置：现在使用谷歌桌面OAuth客户端-无需重定向URI或端口配置！

特性

▶ 快速开始

export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."

uvx workspace-mcp --tool-tier core
uv run main.py --tools gmail drive

1.一键式Claude桌面安装（推荐）

1. 下载： 获取最新消息 google_workspace_mcp.dxt 从“发布”页面
2. 安装： 双击文件–Claude Desktop打开并提示您 安装
3. 配置： 在克劳德桌面→ 设置→ 扩展→ 谷歌工作区MCP，粘贴您的Google OAuth凭据
4. 使用它： 开始一个新的克劳德聊天，并调用任何谷歌工作区工具

为什么选择DXT？

桌面扩展(.dxt)捆绑服务器、依赖项和清单，以便用户从下载→ 工作MCP 一键 -没有终端，没有JSON编辑，没有版本冲突。

所需配置

先决条件

• Python 3.10+
• uvx （用于即时安装）或 紫外线 （用于发展）
• 谷歌云项目 使用OAuth 2.0凭据

配置

console.cloud.google.com

→ Create new project
→ Note project name

APIs & Services → Credentials
→ Create Credentials
→ OAuth Client ID
→ Desktop Application

APIs & Services → Library

Search & enable:
Calendar, Drive, Gmail,
Docs, Sheets, Slides,
Forms, Tasks, Chat, Search

1.1. 凭证：参见 凭证配置 有关详细的设置选项

2. 环境配置:

export OAUTHLIB_INSECURE_TRANSPORT=1

export USER_GOOGLE_EMAIL=\
  your.email@gmail.com

export GOOGLE_PSE_API_KEY=xxx
export GOOGLE_PSE_ENGINE_ID=yyy

3. 服务器配置:

export WORKSPACE_MCP_BASE_URI=
  http://localhost
export WORKSPACE_MCP_PORT=8000

export MCP_ENABLE_OAUTH21=
  true

export USER_GOOGLE_EMAIL=\
  your.email@gmail.com

Google自定义搜索设置

programmablesearchengine.google.com
/controlpanel/create

→ Configure sites or entire web
→ Note your Engine ID (cx)

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

→ Create/select project
→ Enable Custom Search API
→ Create credentials (API Key)

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

启动服务器

uv run main.py

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

uv run main.py \
  --single-user

# Load specific services only
uv run main.py --tools gmail drive calendar
uv run main.py --tools sheets docs

# Combine with other flags
uv run main.py --single-user --tools gmail

uv run main.py --tool-tier core      # ● Essential tools only
uv run main.py --tool-tier extended  # ◐ Core + additional
uv run main.py --tool-tier complete  # ○ All available tools

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

# With tool selection via environment variables
docker run -e TOOL_TIER=core workspace-mcp
docker run -e TOOLS="gmail drive calendar" workspace-mcp

工具层

服务器将工具组织成 三个渐进的层次 以简化部署。选择与您的使用需求和API配额要求相匹配的层。

用法示例

# Basic tier selection
uv run main.py --tool-tier core                            # Start with essential tools only
uv run main.py --tool-tier extended                        # Expand to include management features
uv run main.py --tool-tier complete                        # Enable all available functionality

# Selective service loading with tiers
uv run main.py --tools gmail drive --tool-tier core        # Core tools for specific services
uv run main.py --tools gmail --tool-tier extended          # Extended Gmail functionality only
uv run main.py --tools docs sheets --tool-tier complete    # Full access to Docs and Sheets

📋 凭证配置

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

# Download & place in project root
client_secret.json

# Or specify custom path
export GOOGLE_CLIENT_SECRET_PATH=\
  /path/to/secret.json

cp .env.oauth21 .env
# Edit .env with credentials

🧰 可用工具

备注：所有工具都支持通过以下方式进行自动身份验证 @require_google_service() 带有30分钟服务缓存的装饰器。

工具层图例：

• • 核心：基本功能的基本工具•API使用率最低•入门
• • 扩展的：核心工具+附加功能•常规使用•扩展功能
• • 完成：所有可用工具，包括高级功能•高级用户•API完全访问

连接到克劳德桌面

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

标准模式（默认-建议用于Claude Desktop）

一般来说，您应该使用Claude Desktop的一键式DXT安装程序包。 如果您因某种原因无法配置，可以通过手动配置 claude_desktop_config.json

手动克劳德配置（备选）

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

2.高级/跨平台安装

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

即时命令行界面（uvx）

# Requires Python 3.10+ and uvx
# First, set credentials (see Credential Configuration above)
uvx workspace-mcp --tool-tier core  # or --tools gmail drive calendar

地方发展设置

# Install everything needed for linting, tests, and release tooling
uv sync --group dev

# Run the same linter that git hooks invoke automatically
uv run ruff check .

# Execute the full test suite (async fixtures require pytest-asyncio)
uv run pytest

OAuth 2.1支持（多用户承载令牌身份验证）

该服务器包括对承载令牌身份验证的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.

# OAuth 2.1 requires HTTP transport mode
export MCP_ENABLE_OAUTH21=true
uv run main.py --transport streamable-http

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

无状态模式（容器友好）

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

启用无状态模式：

# Stateless mode requires OAuth 2.1 to be enabled
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检查员：桌面OAuth客户端不需要额外配置。

Claude代码检查器：桌面OAuth客户端不需要额外配置。

外部OAuth 2.1提供者模式

对于由外部系统处理身份验证的场景，服务器支持外部OAuth 2.1提供程序模式。在这种模式下，MCP服务器本身并不管理OAuth流，而是希望在工具调用的Authorization标头中有有效的承载令牌。

启用外部OAuth 2.1提供程序模式：

# External OAuth provider mode requires OAuth 2.1 to be enabled
export MCP_ENABLE_OAUTH21=true
export EXTERNAL_OAUTH21_PROVIDER=true
uv run main.py --transport streamable-http

工作原理：

• 协议级身份验证已禁用：MCP握手(initialize)以及 tools/list 不需要身份验证
• 需要工具级身份验证：所有工具调用必须包括 Authorization: Bearer <token> 头球
• 外部OAuth流：您的外部系统处理OAuth流并获取Google访问令牌
• 令牌验证：服务器通过Google的tokeninfo API验证承载令牌
• 多用户支持：每个请求都根据其承载令牌独立进行身份验证

主要特点：

• 没有本地OAuth流：服务器不提供OAuth回调端点或管理OAuth状态
• 仅限持有者代币：所有身份验证均通过授权标头进行
• 设计无状态：与无缝协作 WORKSPACE_MCP_STATELESS_MODE=true
• 外部身份提供者：与您现有的身份验证基础架构集成
• 工具发现：客户端可以在不进行身份验证的情况下列出可用工具

要求：

• 必须与 MCP_ENABLE_OAUTH21=true
• 令牌验证仍然需要OAuth凭据(GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET)
• 外部系统必须获得有效的Google OAuth访问令牌（ya29.*）
• 每个工具调用请求都必须包含有效的承载令牌

使用案例：

• 与现有身份验证系统集成
• 由您的应用程序管理的自定义OAuth流
• 处理上游身份验证的API网关
• 具有集中身份验证的多租户SaaS应用程序
• 具有自己的OAuth实现的移动或web应用程序

VS代码MCP客户端支持

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

反向代理设置

如果你在反向代理（nginx、Apache、Cloudflare等）后面运行MCP服务器，你有两个配置选项：

问题：当在反向代理后面时，服务器使用内部端口（例如。， http://localhost:8000)但是外部客户端需要公共URL（例如。， https://your-domain.com).

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

# This configures all OAuth endpoints to use your external URL
export WORKSPACE_EXTERNAL_URL="https://your-domain.com"

解决方案2：设置 GOOGLE_OAUTH_REDIRECT_URI 对于回调：

# This only overrides the OAuth callback URL
export GOOGLE_OAUTH_REDIRECT_URI="https://your-domain.com/oauth2callback"

您还可以选择： | OAUTH_CUSTOM_REDIRECT_URIS （可选） |以逗号分隔的附加重定向URI列表| | OAUTH_ALLOWED_ORIGINS （可选） |逗号分隔的其他CORS源列表|

重要:

• 使用 WORKSPACE_EXTERNAL_URL 当所有OAuth端点都应该使用外部URL时（建议用于反向代理设置）
• 使用 GOOGLE_OAUTH_REDIRECT_URI 当您只需要覆盖回调URL时
• 重定向URI必须与您的Google Cloud控制台中配置的完全匹配
• 您的反向代理必须转发与OAuth相关的请求(/oauth2callback, /oauth2/*, /.well-known/*)到MCP服务器

# Configure credentials first (see Credential Configuration section)

# Start with specific tools only
uvx workspace-mcp --tools gmail drive calendar tasks

# Start with tool tiers (recommended for most users)
uvx workspace-mcp --tool-tier core      # Essential tools
uvx workspace-mcp --tool-tier extended  # Core + additional features
uvx workspace-mcp --tool-tier complete  # All tools

# Start in HTTP mode for debugging
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

开发安装（供贡献者使用）:

{
  "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"
      }
    }
  }
}

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

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

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

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

首次身份验证

服务器使用 谷歌桌面OAuth 为了简化身份验证：

• 不需要重定向URI：桌面OAuth客户端无需复杂的回调URL即可处理身份验证
• 自动流量：服务器透明地管理整个OAuth过程
• 运输无关：可在stdio和HTTP模式下无缝工作

调用工具时：

1. 服务器返回授权URL
2. 在浏览器中打开URL并授权
3. Google提供授权码
4. 在提示时粘贴代码（或自动处理）
5. 服务器完成身份验证并重试您的请求

◆ 发展

项目结构

google_workspace_mcp/
├── auth/              # Authentication system with decorators
├── core/              # MCP server and utilities
├── g{service}/        # Service-specific tools
├── main.py            # Server entry point
├── client_secret.json # OAuth credentials (not committed)
└── pyproject.toml     # Dependencies

添加新工具

from auth.service_decorator import require_google_service

@require_google_service("drive", "drive_read")  # Service + scope group
async def your_new_tool(service, param1: str, param2: int = 10):
    """Tool description"""
    # service is automatically injected and cached
    result = service.files().list().execute()
    return result  # Return native Python objects

建筑亮点

• 服务缓存：30分钟TTL减少了身份验证开销
• 范围管理：集中在 SCOPE_GROUPS 便于维护
• 错误处理：本机异常，而不是手动错误构造
• 多服务支持: @require_multiple_services() 用于复杂工具

凭证存储系统

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

特征：

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

配置：

# Optional: Set custom credentials directory
export GOOGLE_MCP_CREDENTIALS_DIR="/path/to/credentials"

# Default locations (if GOOGLE_MCP_CREDENTIALS_DIR not set):
# - ~/.google_workspace_mcp/credentials (if home directory accessible)
# - ./.credentials (fallback)

使用示例：

from auth.credential_store import get_credential_store

# Get the global credential store instance
store = get_credential_store()

# Store credentials for a user
store.store_credential("user@example.com", credentials)

# Retrieve credentials
creds = store.get_credential("user@example.com")

# List all users with stored credentials
users = store.list_users()

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

⊠安全

• 凭证：从不承诺 .env, client_secret.json 或 .credentials/ 目录到源代码管理！
• OAuth回调：用途 http://localhost:8000/oauth2callback 发展（需要 OAUTHLIB_INSECURE_TRANSPORT=1)
• 传输感知回调：Stdio模式仅为OAuth启动一个最小的HTTP服务器，确保回调在所有模式下都能工作
• 生产：使用HTTPS和OAuth 2.1并相应配置
• 范围最小化：工具仅请求必要的权限

≡许可证

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

验证：