AI导哈

Google Workspace文档处理服务

提供Google Docs、Google Sheets和Google Chat的结构化数据读取与图像处理功能的Python服务。

  • by NgoQuocViet2001
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 NgoQuocViet2001/google-workspace-mcp

使用说明

谷歌工作区MCP

Python MCP服务器，用于读取谷歌文档、谷歌表格和谷歌聊天，具有结构化输出和更好的图像处理。

它的作用

  • 将Google文档读取为具有段落、表格、内联对象、定位对象和图像元数据的结构化JSON。
  • 读取谷歌表格值、网格数据、公式、注释、超链接和芯片运行。
  • 以结构化JSON格式列出Google聊天空间、空间成员和消息。
  • 通过以下方式保留表格单元格中的部分文本样式 text_runs 和a annotated_text 用于删除线和下划线等分段的辅助字段。
  • 从以下位置提取网格图纸图像 Drive export -> XLSX.
  • 细胞内检测 IMAGE("...") 公式与图形导出分开。

项目布局

google_workspace_mcp/
  chat.py       # Google Chat normalization helpers
  cli.py        # command-line entrypoint
  client.py     # Google API auth + HTTP client
  common.py     # shared constants and parsing helpers
  docs.py       # Google Docs normalization helpers
  server.py     # FastMCP server instance
  sheets.py     # Google Sheets normalization helpers
  tools.py      # MCP tool definitions
mcp_google_workspace.py  # compatibility wrapper for local scripts/config
tests/

快速开始

从GitHub安装

pip install "git+https://github.com/NgoQuocViet2001/google-workspace-mcp.git"

跨平台运行它的最可靠方法是：

python -m google_workspace_mcp

如果你的Python脚本目录已经打开 PATH，这个较短的启动器也可以工作：

google-workspace-mcp

快速登录OAuth

  1. 在Google Cloud中，创建具有应用程序类型的OAuth客户端ID Desktop app.
  2. 如果已发布的包中已经包含捆绑的OAuth桌面客户端，只需运行：
python -m google_workspace_mcp auth login

这将直接打开浏览器OAuth流。

  1. 如果该包不包括捆绑的OAuth客户端，并且还不存在本地OAuth客户端配置，则CLI会提示一次：
    • Client ID
    • Client Secret

然后，它将可重用的桌面应用程序客户端配置保存在：

$HOME/.google-workspace-mcp/oauth-client-secret.json

并自动打开浏览器OAuth流。首次成功登录后，缓存的令牌存储在：

$HOME/.google-workspace-mcp/oauth-token.json

其他常用命令

python -m google_workspace_mcp auth status
python -m google_workspace_mcp auth logout

CLI命令

使用 python -m google_workspace_mcp ... 下面到处都是。如果 google-workspace-mcp 已打开 PATH，同样的命令也适用于较短的启动器。

  • python -m google_workspace_mcp
  • python -m google_workspace_mcp auth
  • python -m google_workspace_mcp auth login
  • python -m google_workspace_mcp auth login --client-secrets C:\path\to\oauth-client-secret.json
  • python -m google_workspace_mcp auth login --client-id <client-id> --client-secret <client-secret>
  • python -m google_workspace_mcp auth login --token-file C:\path\to\oauth-token.json
  • python -m google_workspace_mcp auth status
  • python -m google_workspace_mcp auth logout

身份验证选项

推荐用于共享到您的Google帐户的私人文件：OAuth桌面客户端

如果文件是私有的，但共享到您的个人谷歌帐户，请为桌面应用程序使用谷歌OAuth客户端ID。

如果你想让最终用户能够运行 python -m google_workspace_mcp auth login 无需额外设置即可直接进入浏览器OAuth流程，在以下位置发布带有捆绑桌面应用程序客户端的包：

google_workspace_mcp/oauth-default-client.json

如果没有捆绑的客户端，CLI将退回到提示一次 Client ID 和 Client Secret，或者它可以从本地JSON文件中读取它们。

  1. 启用：
    • 谷歌网页API
    • 谷歌文档API
    • Google Drive API
    • 谷歌聊天API
  2. 创建具有应用程序类型的OAuth客户端ID Desktop app.
  3. 选择一种设置方法：
    • 最简单：跑步 python -m google_workspace_mcp auth login，粘贴 Client ID 和 Client Secret 一次，让CLI保存它们以备将来登录。
    • 如果你喜欢文件：下载客户端机密JSON。下载的文件名通常类似于 client_secret_<id>.apps.googleusercontent.com.json.
  4. 可选的基于文件的设置：
$HOME/.google-workspace-mcp/oauth-client-secret.json

或设置：

$env:GOOGLE_OAUTH_CLIENT_SECRETS_FILE="C:\path\to\oauth-client-secret.json"
  1. 运行一次性浏览器登录流程：
python -m google_workspace_mcp auth

首次成功登录后，服务器会自动将缓存的OAuth令牌用于私人文档、表格、驱动器和Google聊天调用。您不需要为该流提供单独的API密钥。

默认情况下，这会在以下位置存储一个可刷新的令牌：

$HOME\.google-workspace-mcp\oauth-token.json

使用此选项检查缓存的令牌作用域，并查看哪些作用域仍然缺失：

python -m google_workspace_mcp auth status

如果 auth status 仅显示 drive.readonly，包含以下内容的表格URL gid 和 range 仍然可以通过服务器的驱动器导出回退读取。该回退返回面向值的输出，并省略公式、注释、超链接和富文本元数据，直到您重新运行 python -m google_workspace_mcp auth login 和 spreadsheets.readonly.

如果您需要用特定的客户端机密文件和令牌路径覆盖缓存的令牌，您还可以运行：

python -m google_workspace_mcp auth login --client-secrets C:\path\to\oauth-client-secret.json --token-file C:\path\to\oauth-token.json

如果桌面应用程序客户端JSON已存在 $HOME/.google-workspace-mcp/，这个较短的命令也有效：

python -m google_workspace_mcp auth login

当您使用登录时 --client-secrets，或与 --client-id 加 --client-secret，CLI还将可重用的桌面应用程序客户端JSON保存到 $HOME/.google-workspace-mcp/oauth-client-secret.json 因此，未来的登录可以省略额外的标志。

要稍后删除缓存的OAuth令牌，请运行：

python -m google_workspace_mcp auth logout

如果单独配置 GOOGLE_OAUTH_ACCESS_TOKEN，同时从shell或MCP配置中删除该环境变量。

推荐：服务帐户

使用Google Cloud服务帐户进行最可靠的设置。

  1. 启用：
    • 谷歌网页API
    • 谷歌文档API
    • Google Drive API
    • Google Chat API，如果您计划使用用户指定的承载令牌调用聊天工具
  2. 创建服务帐户密钥。
  3. 与服务帐户电子邮件共享目标文档/表格文件。
  4. 设置：
$env:GOOGLE_SERVICE_ACCOUNT_FILE="C:\path\to\service-account.json"

仅限公用工作表：API密钥

适用于公共谷歌表格阅读。不建议用于文档或驱动器导出。

$env:GOOGLE_API_KEY="your_api_key"

现有承载令牌：OAuth访问令牌

$env:GOOGLE_OAUTH_ACCESS_TOKEN="ya29...."

安装

git clone https://github.com/NgoQuocViet2001/google-workspace-mcp.git
cd google-workspace-mcp
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

从GitHub安装

选项1：克隆存储库

git clone https://github.com/NgoQuocViet2001/google-workspace-mcp.git
cd google-workspace-mcp
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

选项2：直接从GitHub安装

pip install "git+https://github.com/NgoQuocViet2001/google-workspace-mcp.git"

从GitHub安装后，最可靠的运行方式是：

python -m google_workspace_mcp

这避免了 PATH 问题当 pip 将控制台脚本安装到用户站点的scripts目录中。

如果你的Python脚本目录已经打开 PATH，独立命令也可以工作：

google-workspace-mcp

运行服务器

cd <path-to-repo>
.venv\Scripts\python.exe mcp_google_workspace.py

或者，如果你直接从GitHub安装它：

python -m google_workspace_mcp

要为私人用户帐户引导OAuth：

python -m google_workspace_mcp auth

如果你 google-workspace-mcp 启动器已在上可用 PATH，等效的较短命令为：

google-workspace-mcp auth login

要检查当前的身份验证设置：

python -m google_workspace_mcp auth status

要删除缓存的OAuth登录名，请执行以下操作：

python -m google_workspace_mcp auth logout

Codex MCP配置

{
  "mcpServers": {
    "google-workspace": {
      "command": "<path-to-repo>/.venv/Scripts/python.exe",
      "args": ["<path-to-repo>/mcp_google_workspace.py"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRETS_FILE": "C:/path/to/oauth-client-secret.json",
        "GOOGLE_OAUTH_TOKEN_FILE": "C:/path/to/oauth-token.json"
      }
    }
  }
}

仅适用于公共表格，请替换 env 用以下方式阻止：

{
  "GOOGLE_API_KEY": "your_api_key"
}

如果你直接从GitHub将包安装到PATH环境中，你也可以使用：

{
  "mcpServers": {
    "google-workspace": {
      "command": "google-workspace-mcp",
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRETS_FILE": "C:/path/to/oauth-client-secret.json",
        "GOOGLE_OAUTH_TOKEN_FILE": "C:/path/to/oauth-token.json"
      }
    }
  }
}

可用工具

  • diagnose_google_auth
  • resolve_google_file
  • list_google_chat_spaces
  • get_google_chat_space
  • get_google_chat_message
  • read_google_chat_messages
  • read_google_chat_thread
  • list_google_chat_memberships
  • read_sheet_values
  • read_sheet_grid
  • get_sheet_row
  • search_sheet
  • sheet_to_json
  • inspect_sheet_images
  • read_google_doc
  • download_google_doc_images
  • export_google_file

示例提示

替换占位符，例如 <spreadsheet-id>, <sheet-name>，以及 <output-dir> 有自己的价值观。

谷歌表格网址 gid 和 range 自动解决。如果调用者省略了工作表前缀，服务器将使用由以下内容标识的选项卡 gid.

从工作表中读取一行

get_sheet_row(
  "<spreadsheet-id>",
  "<sheet-name>",
  42,
  1
)

read_sheet_values 还接受行样式输入，例如 <sheet-name>!42:42 并自动将其归一化为有效的全行A1范围。

直接从表格URL读取 gid 和 range

read_sheet_values(
  "https://docs.google.com/spreadsheets/d/<spreadsheet-id>/edit?gid=<gid>#gid=<gid>&range=38:38"
)

当缓存的OAuth令牌具有 drive.readonly 但不是 spreadsheets.readonly，通过在幕后将寻址的选项卡/范围导出为CSV，这仍然是成功的。回应包括 source: "drive_export_csv_fallback" 和a auth_warning 因此调用者知道更丰富的网格元数据不可用。

使用公式、注释和链接读取网格数据

read_sheet_grid(
  "<spreadsheet-id>",
  "<sheet-name>!A1:Z200"
)

对于具有部分格式化的单元格， read_sheet_grid() 现在包括：

  • text_runs：来自Google表格的结构化偏移量和样式标志
  • annotated_text：纯文本辅助字符串，例如 [[STRIKE]]old[[/STRIKE]] new

在工作表中搜索

search_sheet(
  "<spreadsheet-id>",
  "login"
)

如果您通过以下方式传递表格URL gid, search_sheet() 默认情况下，只搜索该选项卡，而不是扫描整个工作簿。

列出谷歌聊天空间

list_google_chat_spaces()

阅读来自谷歌聊天空间的消息

read_google_chat_messages() 接受以下资源名称之一 spaces/AAAA... 或者包含空间id的聊天UI URL。

read_google_chat_messages(
  "spaces/AAAA1234567",
  50,
  null,
  null,
  "DESC",
  false
)

从帖子URL读取一个谷歌聊天帖子

read_google_chat_thread() 接受以下线程资源之一 spaces/<space>/threads/<thread> 或聊天UI URL，如 https://chat.google.com/room/<space>/<thread>/<message>.

read_google_chat_thread(
  "https://chat.google.com/room/AAQAyxdRoZo/jVIpmenXnO0/WNSdv6IyQf0?cls=10"
)

当URL包含消息ID时，响应包括以下两项：

  • linked_message：链接引用的确切消息
  • root_message：线程中的第一条消息

如果Google Chat没有公开与URL令牌匹配的API消息资源，则响应设置 linked_message 到 null 并解释了 linked_message_lookup_warning.

在Google聊天空间中列出成员

list_google_chat_memberships(
  "spaces/AAAA1234567"
)

将工作表转换为JSON

sheet_to_json(
  "<spreadsheet-id>",
  "<sheet-name>",
  1
)

从工作表中提取图像

inspect_sheet_images(
  "<spreadsheet-id>",
  "<sheet-name>",
  "C:/path/to/output/sheet-images"
)

读取带有文本和图像元数据的Google文档

read_google_doc(
  "https://docs.google.com/document/d/<doc-id>/edit",
  null,
  false,
  null
)

从谷歌文档下载图片

download_google_doc_images(
  "https://docs.google.com/document/d/<doc-id>/edit",
  "C:/path/to/output/doc-images",
  null
)

实际限制

  • Google Docs的图像元数据可直接通过Docs API获得，因此文档提取能力很强。
  • Google表格并不像单元格数据那样清晰地显示网格上的图像，因此此服务器使用XLSX导出来恢复它们。
  • 谷歌聊天读取需要OAuth作用域，例如 chat.spaces.readonly, chat.messages.readonly，以及 chat.memberships.readonly。如果缓存的令牌较旧，请重新运行 python -m google_workspace_mcp auth login.
  • 谷歌聊天API请求还需要在同一个谷歌云项目中配置聊天应用程序。在 Google Chat API > Configuration，至少填写 App name, Avatar URL，以及 Description，然后保存。
  • 谷歌聊天室URL总是公开空间ID，通常适用于线程读取，但最终的URL令牌不能保证是 spaces/{space}/messages/{message} API资源名称。在这些情况下，服务器仍然可以返回线程和根消息，但不能单独通过Chat API可靠地解析确切的链接回复。
  • 使用OAuth用户凭据，Google Chat私人用户对话最可靠。普通服务帐户通常需要一个配置正确的聊天应用程序流来访问聊天资源。
  • 细胞内 IMAGE("...") 公式与导出的图形图像分开检测。
  • 共享到您的用户帐户的私人文件应使用OAuth桌面客户端流。
  • 共享给机器人身份的私有文件应使用服务帐户。
  • API密钥只适用于公共表单，不能读取Google Chat。
  • drive.readonly 对于上述表格URL回退来说，单独使用就足够了，但谷歌文档仍然需要 documents.readonly.

相关 MCP