Google Workspace MCP 服务器

通过模型上下文协议将 MCP 客户端、AI 助手等连接到 Google Workspace 服务

观看实际操作：

📑 目录

概述
特征
快速入门
可用工具
发展
安全说明
执照

🌐 概述

Google Workspace MCP 服务器使用模型上下文协议 (MCP) 将 Google Workspace 服务（日历、云端硬盘、Gmail 和文档）与 AI 助手及其他应用集成。这使得 AI 系统能够安全高效地访问 Google Workspace 应用中的用户数据并进行交互。

✨ 特点

🔐 OAuth 2.0 身份验证：使用用户授权凭据通过自动令牌刷新和集中身份验证流程安全地连接到 Google API
📅 Google 日历集成：完整的日历管理 - 列出日历、获取事件、创建/修改/删除事件，支持全天和定时事件
📁 Google Drive 集成：搜索文件、列出文件夹内容、读取文件内容以及创建新文件。原生支持提取和检索 .docx、.xlsx 以及其他 Microsoft Office 格式！
📧 Gmail 集成：完整的电子邮件管理 - 搜索消息、检索内容、发送电子邮件和创建草稿，并完全支持所有查询语法
📄 Google Docs 集成：直接从聊天中搜索文档、阅读文档内容、列出文件夹中的文档以及创建新文档！
🔄 多种传输选项：可流式传输的 HTTP + SSE 回退
🔌 mcpo兼容性：轻松将服务器公开为 OpenAPI 端点，以便与 Open WebUI 等工具集成
🧩 可扩展设计：简单的结构，可添加对更多 Google Workspace API 和工具的支持
🔄 集成 OAuth 回调：在端口 8000 上的服务器内直接处理 OAuth 重定向
⚡ 线程安全会话管理：通过线程安全架构实现强大的会话处理，从而提高可靠性

🚀 快速入门

先决条件

Python 3.11+
**uv**包安装程序（或 pip）
为所需 API（日历、云端硬盘、Gmail、文档）启用 OAuth 2.0 凭据的Google Cloud 项目

安装

# Clone the repository (replace with your fork URL if different)
git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp

# Create a virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
uv pip install -e .

配置

在Google Cloud Console中创建OAuth 2.0 凭据（桌面应用程序类型）。
为您的项目启用Google 日历 API 、 Google Drive API 、 Gmail API和Google Docs API 。
将 OAuth 客户端凭据下载为client_secret.json并将其放在项目的根目录中。
在 Google Cloud Console 中，将以下重定向 URI 添加到您的 OAuth 客户端配置。请注意， http://localhost:8000是默认的基准 URI 和端口，您可以通过环境变量（ WORKSPACE_MCP_BASE_URI和WORKSPACE_MCP_PORT ）进行自定义。如果您更改这些值，则必须相应地更新 Google Cloud Console 中的重定向 URI。
http://localhost:8000/oauth2callback
⚠️重要：确保将client_secret.json添加到您的.gitignore文件中，并且永远不会提交到版本控制中。

服务器配置

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

WORKSPACE_MCP_BASE_URI ：设置服务器的基本 URI（默认值： http://localhost ）。这会影响用于 Gemini 原生函数调用的server_url以及OAUTH_REDIRECT_URI 。
WORKSPACE_MCP_PORT ：设置服务器监听的端口（默认值： 8000 ）。这会影响server_url 、 port和OAUTH_REDIRECT_URI 。

使用示例：

export WORKSPACE_MCP_BASE_URI="https://my-custom-domain.com"
export WORKSPACE_MCP_PORT="9000"
uv run main.py

环境设置

在开发过程中，服务器使用 HTTP 进行本地主机 OAuth 回调。在运行服务器之前，请设置此环境变量：

# Allow HTTP for localhost OAuth callbacks (development only!)
export OAUTHLIB_INSECURE_TRANSPORT=1

如果没有这个，您可能会在身份验证流程中遇到“OAuth 2 必须使用 HTTPS”错误。

启动服务器

选择以下方法之一来运行服务器：

python main.py
# or using uv
uv run main.py

在端口 8000 上运行带有 HTTP 传输层的服务器。

多用户 MCP 有点混乱，所以目前所有东西最好在客户端和服务器之间以 1:1 映射的方式运行。一旦 Claude 能够执行 OAuth 2.1 流程，这种情况就会改变，因此此 MCP 构建了一个简化单用户环境的标志。您可以在单用户模式下运行服务器，这将绕过会话到 OAuth 的映射，并使用.credentials目录中的任何可用凭据：

python main.py --single-user
# or using uv
uv run main.py --single-user

在单用户模式下：

服务器自动查找并使用.credentials目录中的任何有效凭据
无需会话映射 - 服务器使用找到的第一个有效凭证文件
适用于开发、测试或单用户部署
仍然需要初始 OAuth 身份验证来创建凭证文件

当您不需要多用户会话管理并且想要简化凭证处理时，此模式特别有用。

您可以使用提供的Dockerfile构建并运行服务器。

# Build the Docker image
docker build -t google-workspace-mcp .

# Run the Docker container
# The -p flag maps the container port 8000 to the host port 8000
# The -v flag mounts the current directory to /app inside the container
# This is useful for development to pick up code changes without rebuilding
docker run -p 8000:8000 -v $(pwd):/app google-workspace-mcp

smithery.yaml文件配置为在 Docker 容器内正确启动服务器。

重要港口

默认端口为8000 ，但可以通过WORKSPACE_MCP_PORT环境变量进行更改。

服务	默认端口	描述
OAuth回调	`8000`	由服务器通过`/oauth2callback`路由内部处理
HTTP模式服务器	`8000`	使用 HTTP 传输时的默认设置

连接到服务器

服务器支持多种连接方式：

克劳德桌面：

可以在任何地方运行并通过mcp-remote使用，或者使用uv run main.py作为参数或使用带有 localhost 的mcp-remote在本地调用。

配置.json：

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

安装mcpo ： uv pip install mcpo或pip install mcpo
创建config.json （请参阅与 Open WebUI 集成）
运行指向您的配置的mcpo ： uvx mcpo --config config.json --port 8001
MCP 服务器 API 可在以下位置访问： http://localhost:8001/google_workspace （或config.json中定义的名称）
OpenAPI 文档（Swagger UI）位于： http://localhost:8001/google_workspace/docs

使用启动命令（用于单 mcp mcpo 使用）：

安装mcpo ： uv pip install mcpo或pip install mcpo
从uvx mcpo --port 8001 --api-key "top-secret" --server-type "streamablehttp" -- http://localhost:8000/mcp开始
MCP 服务器 API 的地址为： http://localhost:8001/openapi.json （或config.json中定义的名称）
OpenAPI 文档（Swagger UI）位于： http://localhost:8001/docs
以 HTTP 模式启动服务器（请参阅启动服务器）
直接发送 MCP JSON 请求到http://localhost:8000
适用于使用curl或自定义 HTTP 客户端等工具进行测试
可用于服务 Claude Desktop 和其他 MCP 客户端，但需通过 mcp-remote 集成新的 Streamable HTTP 传输：
如果愿意，您还可以在 SSE 后备模式下提供服务。

与 Open WebUI 集成

要将此服务器用作 Open WebUI 中的工具提供程序：

创建mcpo配置：创建一个名为config.json的文件，其结构如下，以便 mcpo 将可流式传输的 HTTP 端点用作 OpenAPI 规范工具。
{ "mcpServers": { "google_workspace": { "type": "streamablehttp", "url": "http://localhost:8000/mcp" } } }
启动mcpo服务器：
mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"
此命令启动mcpo代理，在端口 8001 上为您的活动（假设端口 8000）Google Workspace MCP 提供服务。
配置 Open WebUI ：
- 导航到您的 Open WebUI 设置
- 转到“连接”->“工具”
- 点击“添加工具”
- 输入服务器 URL： http://localhost:8001/google_workspace （与config.json中的mcpo基本 URL 和服务器名称匹配）
- 如果您在mcpo中使用了--api-key ，请将其作为 API 密钥输入
- 保存配置
- 现在，在 Open WebUI 中与模型交互时应该可以使用 Google Workspace 工具

首次身份验证

当调用需要 Google API 访问的工具时：

如果已向工具提供user_google_email且凭证缺失/无效：服务器将自动启动 OAuth 2.0 流程。授权 URL 将在 MCP 响应中返回（或打印到控制台）。
如果未提供user_google_email且凭证缺失/无效：该工具将返回一条错误消息，引导 LLM 使用集中式start_google_auth工具。LLM 随后应使用用户的电子邮件和相应的service_name （例如，“Google 日历”、“Google 文档”、“Gmail”、“Google 云端硬盘”）调用start_google_auth 。这还将返回一个授权 URL。

用户步骤（获得授权 URL 后）：

在 Web 浏览器中打开提供的授权 URL。
登录 Google 帐户并授予指定服务所请求的权限。
授权后，Google 会将浏览器重定向到http://localhost:8000/oauth2callback （或您配置的重定向 URI）。
MCP 服务器处理此回调，将授权码与令牌交换，并安全地存储凭证。
然后，LLM 可以重试原始请求。在刷新令牌过期或被撤销之前，对同一用户和服务的后续调用应该无需重新进行身份验证即可正常工作。

🧰 可用工具

注意：如果尚未存储有效凭据，且已向工具提供user_google_email ，则首次使用任何特定 Google 服务的工具都可能触发 OAuth 身份验证流程。如果需要身份验证，但未向工具提供user_google_email ，则 LLM 应使用集中式start_google_auth工具（定义在core/server.py中），并输入用户的电子邮件和相应的service_name 。

📅 Google 日历

来源： gcalendar/calendar_tools.py

工具	描述	参数
`start_google_auth`	（集中在`core/server.py`中）为特定的 Google 帐户和服务启动 OAuth 2.0 身份验证流程。当没有可用的有效凭证，或者工具因缺少身份验证而失败且未提供电子邮件时，请使用此选项。	• `user_google_email` （必填）：用户的 Google 电子邮件地址 • `service_name` （必填）：Google 服务名称（例如，“Google 日历”、“Google 文档”、“Gmail”、“Google 云端硬盘”）
`list_calendars`	列出经过身份验证的用户可以访问的所有日历。	• `user_google_email` （可选）：如果会话未通过身份验证则使用 • `mcp_session_id` （自动注入）
`get_events`	从指定日历中检索某个时间范围内即将发生的事件。	• `calendar_id` （可选）：日历 ID（默认值： `primary` ）• `time_min` （可选）：开始时间（RFC3339 或`YYYY-MM-DD` ）• `time_max` （可选）：结束时间（RFC3339 或`YYYY-MM-DD` ）• `max_results` （可选）：最大事件数（默认值：25）• `user_google_email` （可选）• `mcp_session_id` （自动注入）
`create_event`	创建新的日历事件。支持全天和定时事件。	• `summary` （必填）：活动标题• `start_time` （必填）：开始时间（RFC3339 或`YYYY-MM-DD` ）• `end_time` （必填）：结束时间（RFC3339 或`YYYY-MM-DD` ）• `calendar_id` （可选）：日历 ID（默认： `primary` ）• `description` 、 `location` 、 `attendees` 、 `timezone` （可选）• `user_google_email` （可选）• `mcp_session_id` （自动注入）
`modify_event`	根据 ID 更新现有事件。仅修改提供的字段。	• `event_id` （必需）：要修改的事件的 ID • `calendar_id` （可选）：日历 ID（默认值： `primary` ）• `summary` 、 `start_time` 、 `end_time` 、 `description` 、 `location` 、 `attendees` 、 `timezone` （可选）• `user_google_email` （可选）• `mcp_session_id` （自动注入）
`delete_event`	根据 ID 删除事件。	• `event_id` （必需）：要删除的事件的 ID • `calendar_id` （可选）：日历 ID（默认值： `primary` ） • `user_google_email` （可选） • `mcp_session_id` （自动注入）

ℹ️ 所有日历工具都支持通过当前 MCP 会话 ( mcp_session_id ) 进行身份验证，或回退到user_google_email进行身份验证。如果两者都不可用且需要身份验证，该工具将返回错误，提示 LLM 使用集中式start_google_auth工具，并输入用户的电子邮件和service_name="Google Calendar" 。

🕒 日期/时间参数：工具既接受完整的 RFC3339 时间戳（例如 2024-05-12T10:00:00Z），也接受简单日期（例如 2024-05-12）。服务器会根据需要自动格式化。

📁 Google 云端硬盘

来源： gdrive/drive_tools.py

工具	描述	参数
`search_drive_files`	在用户的云端硬盘中搜索文件和文件夹	• `query` （必需）：搜索查询字符串（例如， `name contains 'report'` ）• `max_results` （可选）：要返回的最大文件数
`get_drive_file_content`	检索特定文件的内容	• `file_id` （必需）：文件的 ID • `mime_type` （可选）：指定所需的导出格式
`list_drive_items`	列出特定文件夹或根目录中的文件和文件夹	• `folder_id` （可选）：要列出的文件夹的 ID（默认为根）• `max_results` （可选）：要返回的最大项目数
`create_drive_file`	在 Google Drive 中创建新文件	• `name` （必需）：新文件的名称 • `content` （必需）：要写入文件的文本内容 • `folder_id` （可选）：父文件夹的 ID • `mime_type` （可选）：文件的 MIME 类型（默认为`text/plain` ）

查询语法：有关 Google Drive 搜索查询，请参阅Drive 搜索查询语法

📧 Gmail

来源： gmail/gmail_tools.py

工具	描述	参数
`search_gmail_messages`	使用标准 Gmail 搜索运算符（发件人、主题等）搜索电子邮件。	• `query` （必需）：搜索字符串（例如， `"from:foo subject:bar is:unread"` ）• `user_google_email` （可选）• `page_size` （可选，默认值：10）• `mcp_session_id` （自动注入）
`get_gmail_message_content`	通过消息 ID 获取电子邮件的主题、发件人和纯文本正文。	• `message_id` （必需）• `user_google_email` （可选）• `mcp_session_id` （自动注入）
`send_gmail_message`	使用用户的 Gmail 帐户发送纯文本电子邮件。	• `to` （必填）：收件人电子邮件地址 • `subject` （必填） • `body` （必填） • `user_google_email` （可选） • `mcp_session_id` （自动注入）
`draft_gmail_message`	在用户的 Gmail 帐户中创建电子邮件草稿。	• `subject` （必填）：电子邮件主题• `body` （必填）：电子邮件正文（纯文本）• `to` （可选）：收件人电子邮件地址• `user_google_email` （可选）• `mcp_session_id` （自动注入）

查询语法：有关 Gmail 搜索查询，请参阅Gmail 搜索查询语法

📝 Google 文档

来源： gdocs/docs_tools.py

工具	描述	参数
`search_docs`	按名称搜索 Google Docs（使用 Drive API）。	• `query` （必需）：在文档名称中搜索的文本• `user_google_email` （可选）• `page_size` （可选，默认值：10）• `mcp_session_id` （自动注入）
`get_doc_content`	通过文档 ID 检索 Google Doc 的纯文本内容。	• `document_id` （必需）• `user_google_email` （可选）• `mcp_session_id` （自动注入）
`list_docs_in_folder`	列出给定 Drive 文件夹内的所有 Google Docs（按文件夹 ID，默认 = `root` ）。	• `folder_id` （可选，默认值： `'root'` ）• `user_google_email` （可选）• `page_size` （可选，默认值：100）• `mcp_session_id` （自动注入）
`create_doc`	创建一个新的 Google Doc，可选择包含初始内容。	• `title` （必填）：文档名称• `content` （可选，默认值：空）• `user_google_email` （可选）• `mcp_session_id` （自动注入）

🛠️ 开发

项目结构

google_workspace_mcp/
├── .venv/             # Virtual environment (created by uv)
├── auth/              # OAuth handling logic (google_auth.py, oauth_manager.py)
├── core/              # Core MCP server logic (server.py)
├── gcalendar/         # Google Calendar tools (calendar_tools.py)
├── gdocs/             # Google Docs tools (docs_tools.py)
├── gdrive/            # Google Drive tools (drive_tools.py)
├── gmail/             # Gmail tools (gmail_tools.py)
├── .gitignore         # Git ignore file
├── client_secret.json # Google OAuth Credentials (DO NOT COMMIT)
├── config.json        # Example mcpo configuration
├── main.py            # Main server entry point (imports tools)
├── mcp_server_debug.log # Log file for debugging
├── pyproject.toml     # Project metadata and dependencies (for uv/pip)
├── README.md          # This file
├── uv.lock            # uv lock file

OAuth 的端口处理

服务器巧妙地处理了 OAuth 2.0 重定向 URI（ /oauth2callback ），而无需单独的 Web 服务器框架：

在 HTTP 模式或通过mcpo运行时，它利用底层 MCP 库内置的 HTTP 服务器功能
专门为端口8000上的/oauth2callback注册了自定义 MCP 路由
当 Google 在授权后将用户重定向回来时，MCP 服务器会拦截此路由上的请求
auth模块提取授权码并完成token交换
这需要在本地运行时设置OAUTHLIB_INSECURE_TRANSPORT=1 ，因为回调使用http://localhost

调试

检查mcp_server_debug.log获取详细日志，包括身份验证步骤和 API 调用。如有需要，请启用调试日志记录。

验证client_secret.json是否正确且存在
确保在 Google Cloud Console 中配置了正确的重定向 URI（ http://localhost:8000/oauth2callback ）
确认您的 Google Cloud 项目中已启用必要的 API（日历、云端硬盘、Gmail）
检查服务器进程运行环境中是否设置了OAUTHLIB_INSECURE_TRANSPORT=1
在基于浏览器的 OAuth 流程中查找特定的错误消息

检查服务器日志中是否有从 Google API 返回的回溯或错误消息。

添加新工具

选择或创建适当的模块（例如， gdocs/gdocs_tools.py ）
导入必要的库（Google API 客户端库等）
为你的工具逻辑定义一个async函数。使用类型提示作为参数
使用@server.tool("your_tool_name")修饰函数
在函数内部，获取经过身份验证的凭据：

from auth.google_auth import get_credentials, CONFIG_CLIENT_SECRETS_PATH
# ...
credentials = await asyncio.to_thread(
    get_credentials,
    user_google_email=your_user_email_variable, # Optional, can be None if session_id is primary
    required_scopes=YOUR_SPECIFIC_SCOPES_LIST,  # e.g., [CALENDAR_READONLY_SCOPE]
    client_secrets_path=CONFIG_CLIENT_SECRETS_PATH,
    session_id=your_mcp_session_id_variable    # Usually injected via Header
)
if not credentials or not credentials.valid:
    # Handle missing/invalid credentials, possibly by calling start_auth_flow
    # from auth.google_auth (which is what service-specific start_auth tools do)
    pass

构建 Google API 服务客户端： service = build('drive', 'v3', credentials=credentials)
实现调用 Google API 的逻辑
妥善处理潜在错误
将结果返回为 JSON 可序列化的字典或列表
在main.py中导入工具函数，以便它在服务器上注册
在工具模块中定义必要的特定于服务的范围常量
如果需要新的依赖项，请更新pyproject.toml

范围管理： config/google_config.py中的全局SCOPES列表用于初始 OAuth 同意屏幕。各个工具在调用get_credentials时，应该请求所需的最小required_scopes 。

🔒 安全说明

client_secret.json ：此文件包含敏感凭据。切勿将其提交到版本控制。请确保将其列在您的.gitignore文件中。请妥善保管。
用户令牌：经过身份验证的用户凭据（刷新令牌）存储在本地文件中，例如credentials-<user_id_hash>.json 。由于这些文件会授予访问用户 Google 帐户数据的权限，因此请务必妥善保护它们。请确保它们也位于.gitignore中。
OAuth 回调安全性：在开发过程中，已安装应用的标准 OAuth 回调方式是使用http://localhost ，但需要设置OAUTHLIB_INSECURE_TRANSPORT=1 。对于 localhost 以外的生产部署，必须使用 HTTPS 作为回调 URI，并在 Google Cloud Console 中进行相应配置。
mcpo安全性：如果使用mcpo通过网络公开服务器，请考虑：
- 使用--api-key选项进行基本身份验证
- 在反向代理（如 Nginx 或 Caddy）后面运行mcpo来处理 HTTPS 终止、正确的日志记录和更强大的身份验证
- 如果将mcpo暴露到 localhost 之外，则仅将其绑定到受信任的网络接口
范围管理：服务器会为日历、云端硬盘和 Gmail 请求特定的 OAuth 范围（权限）。用户在初始身份验证期间会根据这些范围授予访问权限。请勿请求超出已实现工具所需范围的范围。

截图：

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

Google Workspace MCP Server