Google Workspace MCP 服务器

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

观看演示：

---

📑 目录

• 概述
• 功能
• 快速开始
  • 前提条件
  • 安装
  • 配置
  • 启动服务器
  • 连接到服务器
  • 与 Open WebUI 集成
  • 首次认证
• 可用工具
  • 日历
  • Google 云端硬盘
  • Gmail
  • Google 文档
• 开发
  • 项目结构
  • OAuth 端口处理
  • 调试
  • 添加新工具
• 安全注意事项
• 许可证

---

🌐 概述

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

---

✨ 功能

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

---

🚀 快速开始

前提条件

• Python 3.11+
• uv 包管理器（或 pip）
• 启用所需 API 的 OAuth 2.0 凭据的 Google Cloud 项目（日历、云端硬盘、Gmail、文档）

安装

bash

克隆仓库（如果不同，请替换为您的 fork URL）

git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp

创建虚拟环境并安装依赖项

uv venv
source .venv/bin/activate # 在 Windows 上使用 .venvScriptsactivate
uv pip install -e .

配置1. 在Google Cloud Console中创建OAuth 2.0 凭据（桌面应用程序类型）。

1. 为您的项目启用Google Calendar API、Google Drive API、Gmail API 和 Google Docs API。

2. 将 OAuth 客户端凭据下载为 client_secret.json 并放置在项目的根目录中。

3. 向 Google Cloud Console 中的 OAuth 客户端配置添加以下重定向 URI。请注意，http://localhost:8000 是默认的基础 URI 和端口，可以通过环境变量 (WORKSPACE_MCP_BASE_URI 和 WORKSPACE_MCP_PORT) 进行自定义。如果您更改了这些设置，则必须相应地更新 Google Cloud Console 中的重定向 URI。

   http://localhost:8000/oauth2callback

4. ⚠️ 重要提示：确保将 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。

示例用法：

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

环境设置

开发期间，服务器使用 HTTP 来处理本地主机上的 OAuth 回调。在运行服务器之前，请设置此环境变量：

bash

允许 HTTP 用于本地主机 OAuth 回调（仅限开发！）

export OAUTHLIB_INSECURE_TRANSPORT=1

如果不这样做，在认证流程中可能会遇到 "OAuth 2 必须使用 HTTPS" 的错误。

启动服务器

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

bash
python main.py

或者使用 uv

uv run main.py

以 HTTP 传输层在 8000 端口上运行服务器。

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

bash
python main.py --single-user

或者使用 uv

uv run main.py --single-user

在单用户模式下：

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

当您不需要多用户会话管理并且希望简化凭据处理时，这种模式特别有帮助。

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

bash

构建 Docker 镜像

docker build -t google-workspace-mcp .

运行 Docker 容器

-p 标志将容器端口 8000 映射到主机端口 8000

-v 标志将当前目录挂载到容器内的 /app

这对于开发很有用，可以在不重新构建的情况下拾取代码更改

docker run -p 8000:8000 -v $(pwd):/app google-workspace-mcp

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

重要端口

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

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

连接到服务器

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

Claude Desktop:

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

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

1. 安装 mcpo: uv pip install mcpo 或 pip install mcpo
2. 创建一个 config.json（参见 与 Open WebUI 集成）
3. 运行 mcpo 并指向您的配置文件: uvx mcpo --config config.json --port 8001
4. MCP 服务器 API 将在以下位置可用: http://localhost:8001/google_workspace（或在 config.json 中定义的名称）
5. OpenAPI 文档（Swagger UI）可在以下位置获取: http://localhost:8001/google_workspace/docs

使用启动命令（适用于单个 MCP 的 mcpo 使用）:

1. 安装 mcpo: uv pip install mcpo 或 pip install mcpo
2. 启动命令为: uvx mcpo --port 8001 --api-key "top-secret" --server-type "streamablehttp" -- http://localhost:8000/mcp
3. MCP 服务器 API 将在以下位置可用: http://localhost:8001/openapi.json（或在 config.json 中定义的名称）
4. OpenAPI 文档（Swagger UI）可在以下位置获取: http://localhost:8001/docs

1. 在 HTTP 模式下启动服务器（参见 启动服务器）
2. 直接向 http://localhost:8000 发送 MCP JSON 请求
3. 对于使用 curl 或自定义 HTTP 客户端进行测试非常有用
4. 可用于服务 Claude Desktop 及其他尚未通过 mcp-remote 集成新的 Streamable HTTP 传输的 MCP 客户端：
5. 如果需要，您还可以在 SSE 回退模式下提供服务。

与 Open WebUI 集成

要将此服务器作为工具提供商在 Open WebUI 中使用：

1. 创建 mcpo 配置:
   创建一个名为 config.json 的文件，具有以下结构，以便 mcpo 使可流式传输的 HTTP 端点作为 OpenAPI 规范工具可用。

   json
   {
   "mcpServers": {
   "google_workspace": {
   "type": "streamablehttp",
   "url": "http://localhost:8000/mcp"
   }
   }
   }

2. 启动 mcpo 服务器:
   bash
   mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"

   此命令启动 mcpo 代理，在端口 8001 上提供您的活动（假设端口 8000）Google Workspace MCP。

3. 配置 Open WebUI:

   • 导航到您的 Open WebUI 设置
   • 转到“Connections” -> “Tools”
   • 单击“Add Tool”
   • 输入服务器 URL: http://localhost:8001/google_workspace（匹配 mcpo 基础 URL 和来自 config.json 的服务器名称）
   • 如果您使用了带有 mcpo 的 --api-key，请输入它作为 API Key
   • 保存配置
   • 当与 Open WebUI 中的模型交互时，现在应该可以使用 Google Workspace 工具了

首次认证

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

• 如果提供了 user_google_email 给工具且凭据缺失/无效: 服务器会自动启动 OAuth 2.0 流程。授权 URL 将在 MCP 响应中返回（或打印到控制台）。
• 如果没有提供 user_google_email 且凭据缺失/无效: 工具将返回一条错误消息，指导 LLM 使用集中化的 start_google_auth 工具。LLM 应该随后使用用户的电子邮件和服务名称（例如，“Google Calendar”，“Google Docs”，“Gmail”，“Google Drive”）调用 start_google_auth。这也将返回一个授权 URL。用户操作步骤（在获得授权URL后）：

1. 在网页浏览器中打开提供的授权URL。
2. 登录Google账户并授予指定服务所需的权限。
3. 授权后，Google会将浏览器重定向到http://localhost:8000/oauth2callback（或您配置的重定向URI）。
4. MCP服务器处理此回调，用授权码交换令牌，并安全地存储凭证。
5. LLM随后可以重试原始请求。对于同一用户和服务的后续调用，在刷新令牌过期或被撤销之前，无需重新认证。

---

🧰 可用工具

注意：首次使用任何特定Google服务的工具时，如果尚未存储有效的凭证且提供了user_google_email，则可能会触发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 Calendar", "Google Docs", "Gmail", "Google Drive"）
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 Drive

源文件: gdrive/drive_tools.py

工具	描述	参数
search_drive_files	在用户的Drive中搜索文件和文件夹	• 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 Search Query Syntax

📧 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 Search Query Syntax

📝 Google Docs

源文件: gdocs/docs_tools.py

工具	描述	参数
search_docs	通过名称搜索Google文档（使用Drive API）。	• query (必需): 在文档名称中搜索的文本• user_google_email (可选)• page_size (可选，默认值: 10)• mcp_session_id (自动注入)
get_doc_content	通过文档ID检索Google文档的纯文本内容。	• document_id (必需)• user_google_email (可选)• mcp_session_id (自动注入)
create_doc	创建一个新的 Google 文档，可选地带有初始内容。	• title（必需）：文档名称• content（可选，默认为空）• user_google_email（可选）• mcp_session_id（自动注入）

---

🛠️ 开发

项目结构

google_workspace_mcp/
├── .venv/ # 虚拟环境（由 uv 创建）
├── auth/ # OAuth 处理逻辑（google_auth.py, oauth_manager.py）
├── core/ # 核心 MCP 服务器逻辑（server.py）
├── gcalendar/ # Google 日历工具（calendar_tools.py）
├── gdocs/ # Google 文档工具（docs_tools.py）
├── gdrive/ # Google 网盘工具（drive_tools.py）
├── gmail/ # Gmail 工具（gmail_tools.py）
├── .gitignore # Git 忽略文件
├── client_secret.json # Google OAuth 凭证（不要提交）
├── config.json # 示例 mcpo 配置
├── main.py # 主服务器入口点（导入工具）
├── mcp_server_debug.log # 用于调试的日志文件
├── pyproject.toml # 项目元数据和依赖项（供 uv/pip 使用）
├── README.md # 本文件
├── uv.lock # uv 锁文件

OAuth 的端口处理

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

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

调试

检查 mcp_server_debug.log 以获取详细的日志，包括认证步骤和 API 调用。如果需要，可以启用调试日志。

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

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

添加新工具

1. 选择或创建适当的模块（例如，gdocs/gdocs_tools.py）
2. 导入必要的库（Google API 客户端库等）
3. 为您的工具逻辑定义一个 async 函数。使用类型提示来标注参数
4. 用 @server.tool("your_tool_name") 装饰该函数
5. 在函数内部，获取认证凭据：

python
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, # 可选，如果 session_id 是主要的则可以为 None
required_scopes=YOUR_SPECIFIC_SCOPES_LIST, # 例如，[CALENDAR_READONLY_SCOPE]
client_secrets_path=CONFIG_CLIENT_SECRETS_PATH,
session_id=your_mcp_session_id_variable # 通常通过 Header 注入
)
if not credentials or not credentials.valid:
# 处理缺失或无效的凭据，可能通过调用 auth.google_auth 中的 start_auth_flow 来处理
# 这是服务特定的 start_auth 工具所做的
pass6. 构建 Google API 服务客户端：service = build('drive', 'v3', credentials=credentials)
7. 实现调用 Google API 的逻辑
8. 优雅地处理潜在错误
9. 将结果作为可 JSON 序列化的字典或列表返回
10. 在 main.py 中导入工具函数，以便它在服务器上注册
11. 在您的工具模块中定义必要的特定于服务的作用域常量
12. 如果需要新的依赖项，请更新 pyproject.toml

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

---

🔒 安全注意事项

• client_secret.json：此文件包含敏感凭据。切勿将其提交到版本控制系统。确保它被列入 .gitignore 文件中。安全存储该文件。

• 用户令牌：已认证的用户凭据（刷新令牌）本地存储在类似 credentials-<user_id_hash>.json 的文件中。保护这些文件，因为它们授予对用户 Google 账户数据的访问权限。确保这些文件也在 .gitignore 中。

• OAuth 回调安全性：对于安装的应用程序，在开发期间使用 http://localhost 作为 OAuth 回调是标准做法，但需要设置 OAUTHLIB_INSECURE_TRANSPORT=1。对于非本地主机的生产部署，您必须为回调 URI 使用 HTTPS，并在 Google Cloud Console 中相应配置。

• mcpo 安全性：如果使用 mcpo 将服务器暴露在网络上，请考虑：

  • 使用 --api-key 选项进行基本身份验证
  • 在 mcpo 后面运行反向代理（如 Nginx 或 Caddy），以处理 HTTPS 终止、适当的日志记录和更强大的身份验证
  • 如果将 mcpo 暴露到本地主机之外，仅绑定到受信任的网络接口

• 作用域管理：服务器为 Calendar、Drive 和 Gmail 请求特定的 OAuth 作用域（权限）。用户在初次认证时基于这些作用域授予访问权限。不要为实现的工具请求比必要更广泛的作用域。

---

屏幕截图：

📄 许可证

本项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。