google-workspace-mcp

一个用于构建五个独立的远程 MCP 服务器的项目，服务于 Google Workspace：Gmail、Google Calendar、Google Drive、Google Sheets 和 Google Docs。

状态：pre-alpha。 MCP 服务器尚未可用。当前仓库包含包脚手架、五个占位入口点、下游 OAuth 状态核心以及不可变的按服务配置。

当前状态

已实现：

• 一个包含五个控制台入口点的 Python 包；

• 基于 SQLite 的下游 OAuth 状态；

• OAuth 客户端注册和 PKCE；

• 令牌绑定到规范的 resource；

• 刷新令牌轮换、重放检测和家族撤销；

• 服务和资源的不可变状态所有权元数据；

• 具有严格端口和令牌 TTL 验证的不可变按服务配置。

所有五个控制台入口点均为占位符，退出时显示服务未构建的消息。HTTP/MCP 传输、Google API 集成、服务工具和部署配置尚未实现。

Related MCP server: google-workspace-mcp-advanced

计划中的服务

下表描述了目标范围。这些功能目前尚不可用。

在目标架构中，每个服务作为独立进程运行，拥有自己的 MCP 端点、工具注册表、Google OAuth 作用域、Google 凭据和下游 OAuth 状态。

目标授权架构

设计使用两个独立的层：

客户端到服务。 MCP 客户端使用带 PKCE 的 OAuth 2.1。每个访问令牌绑定到一个 resource，刷新令牌轮换并带有重放检测。

服务到 Google。 每个服务使用独立的 Google 凭据和所需的最小 OAuth 作用域。Google 刷新令牌永远不会返回给 MCP 客户端。

目前仅存在第一层的状态核心。HTTP 端点和第二授权层尚未实现。

技术

• Python 3.14

• uv

• MCP Python SDK

• Pydantic

• Google API Python Client

开发先决条件

• Git

• Python 3.14

• uv

在实现 Google API 集成后，将需要 Google Cloud 项目和 OAuth 客户端。当前版本不使用它们。

开发设置

git clone https://github.com/hawkxdev/google-workspace-mcp.git
cd google-workspace-mcp
uv sync --dev

虚拟环境无需激活。通过 uv run 运行命令。

检查

uv run --no-sync pytest -q
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync mypy src

检查已安装的依赖版本时需要 --no-sync 标志。普通的 uv run 可能会根据锁文件重新同步环境。

结构

贡献

项目处于早期开发阶段。在进行重大更改之前，请打开一个 issue 描述提议的行为。更改不得将五个服务合并为一个进程、在服务之间共享凭据或引入 OAuth 绕过。

来源

该项目根据 MIT 许可证改编自 jimprosser/obsidian-web-mcp 的 OAuth 2.1 核心。有关详细信息，请参阅 NOTICE。

下游 OAuth 2.1 核心基于修订版 7e6a52d791a50e3bd533df1060217973ab5be1c8。它包含针对客户端和令牌生命周期、刷新令牌轮换、重放检测和 resource 规范化的额外修复。

原始项目的 Obsidian 存储和 Git 同步功能未被复制。

此项目使用 mcp>=2,<3。MCP 2.0 中移除的 mcp.server.fastmcp 包不是必需的；未来的组合将使用 mcp.server.mcpserver。

作者

Sergey Sokolkin (@hawkxdev)

许可证

MIT，请参阅 LICENSE。