lite-google-workspace-mcp

用于 Gmail 和 Google Calendar 的轻量级 MCP 服务器。每个 Google 账户作为独立进程运行，各自监听独立端口。

重要的安全特性：直接发送 Gmail 邮件需要每个账户配置 allowed_recipients 列表。如果该列表缺失或为空，所有发送操作都会被阻止。该白名单仅适用于 send_gmail_message；draft_gmail_message 不受限制，这样智能体可以准备草稿供人工审核，但无法直接发送。

工作原理

Claude Code  --HTTP-->  lite-google-workspace-mcp (port 8001)  --Google API-->  account-A@gmail.com
             --HTTP-->  lite-google-workspace-mcp (port 8002)  --Google API-->  account-B@umd.edu

• 每个 Google 账户一个进程，各自监听独立端口

• OAuth 令牌本地存储于 ~/.config/lite-google-workspace-mcp/tokens/<account>.json

• 通过 google-auth 自动处理令牌刷新

• 每个账户暴露 21 个工具：Gmail（搜索、读取、发送、草稿、标签、过滤器）+ Calendar（事件、忙闲查询、不在办公室、专注时间）

Related MCP server: fastmcp-gsuite

前置条件

1. 一个已启用 Gmail API 和 Google Calendar API 的 GCP 项目

2. 一个 OAuth 2.0 凭据（Web 应用类型），重定向 URI 为 http://localhost:8000/oauth2callback

3. 下载凭据 JSON 并保存为 ~/.config/lite-google-workspace-mcp/client_secret.json

安装

git clone https://github.com/WhymustIhaveaname/lite-google-workspace-mcp.git
cd lite-google-workspace-mcp
uv sync

首次设置

1. 配置端口

创建 ~/.config/lite-google-workspace-mcp/config.toml：

[accounts.myaccount]
port = 8001

[accounts.work]
port = 8002
allowed_recipients = ["boss@company.com", "team@company.com"]
allowed_body_formats = ["html"]

账户名称只是你选择的标签，它对应一个令牌文件和一个端口。

send_gmail_message 只会投递到 allowed_recipients 中明确列出的地址（对收件人/抄送/密送进行不区分大小写的检查）。如果 allowed_recipients 被省略或为空，所有发送都会被阻止。无法解析为地址的收件人字段会被视为不允许而非跳过，因此特殊分隔符无法将地址绕过检查。草稿永远不会被投递，因此 draft_gmail_message 不受此列表限制。

send_gmail_message 和 draft_gmail_message 都只接受 allowed_body_formats 中列出的格式。如果该选项被省略，默认值为 ["html"]，因此纯文本消息会被阻止。仅当该账户需要创建或发送纯文本邮件时，才显式添加 "plain"。

这两个选项都必须是 TOML 字符串数组，且 allowed_body_formats 只接受 "plain" 和 "html"。其他任何值都会中止服务器启动，而不是静默阻止所有消息。

如果附件无法读取或解码，则不会发送任何内容，也不会创建草稿。错误信息会指明失败的附件，以便在重试前修复或删除它。

2. 授权账户

uv run lite-google-workspace-mcp auth myaccount

这会打印一个 OAuth URL 并打开你的浏览器。使用你想要关联的 Google 账户登录，授予权限（如果需要，可以跳过某些作用域），令牌会保存在本地。

对每个账户重复此操作。

3. 启动服务器

手动方式：

uv run lite-google-workspace-mcp serve --account myaccount

使用 systemd（推荐）：

cp contrib/lite-google-workspace-mcp@.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now lite-google-workspace-mcp@myaccount

4. 连接到 Claude Code

claude mcp add --scope user --transport http lite-gmail-myaccount http://localhost:8001/mcp

重新授权

如果令牌过期或你想更改已授予的作用域：

# Stop the service first (auth uses port 8000 which must be free)
systemctl --user stop lite-google-workspace-mcp@myaccount

# Re-authorize
uv run lite-google-workspace-mcp auth myaccount

# Restart
systemctl --user start lite-google-workspace-mcp@myaccount

令牌每 7 天过期

如果 OAuth 同意屏幕具有外部用户类型和"测试中"发布状态，Google 会在同意后 7 天使每个刷新令牌过期（这适用于基本个人资料/电子邮件之外的任何作用域）。服务随后会因 invalid_grant: Token has been expired or revoked 而无法启动，重新授权只会重置 7 天倒计时。

解决办法是将应用发布到生产环境：GCP 控制台 > API 和服务 > OAuth 同意屏幕 > 发布应用。生产环境的刷新令牌不会按时间过期。使用受限的 Gmail 作用域时，在验证之前你会看到"应用未经验证"的警告，这对个人或自托管使用是无害的。

工具

Gmail（14 个工具）

Calendar（7 个工具）

开发

uv sync --extra dev
uv run pytest
uv run ruff check src/