lite-google-workspace-mcp
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
前置条件
一个已启用 Gmail API 和 Google Calendar API 的 GCP 项目
一个 OAuth 2.0 凭据(Web 应用类型),重定向 URI 为
http://localhost:8000/oauth2callback下载凭据 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@myaccount4. 连接到 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 个工具)
工具 | 描述 |
search_gmail_messages | 按 Gmail 查询语法搜索 |
get_gmail_message_content | 读取单条消息 |
get_gmail_messages_content_batch | 批量读取多条消息 |
get_gmail_thread_content | 读取整个会话线程 |
get_gmail_threads_content_batch | 批量读取多个会话线程 |
get_gmail_attachment_content | 下载附件 |
send_gmail_message | 发送(纯文本或 HTML,支持附件) |
draft_gmail_message | 创建草稿 |
list_gmail_labels | 列出所有标签 |
manage_gmail_label | 创建/更新/删除标签 |
list_gmail_filters | 列出所有过滤器 |
manage_gmail_filter | 创建/删除过滤器 |
modify_gmail_message_labels | 在消息上添加/移除标签 |
batch_modify_gmail_message_labels | 批量修改标签 |
Calendar(7 个工具)
工具 | 描述 |
list_calendars | 列出所有日历 |
get_events | 按 ID 或时间范围获取事件 |
manage_event | 创建/更新/删除/回复事件 |
manage_out_of_office | 创建/列出/更新/删除不在办公室时段 |
manage_focus_time | 创建/列出/更新/删除专注时间 |
query_freebusy | 检查忙闲状态 |
create_calendar | 创建新日历 |
开发
uv sync --extra dev
uv run pytest
uv run ruff check src/Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
A MCP server for Gmail that lets you search, read, and draft emails and replies.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server to interact with Google Gmail and Calendar APIs. Supports multiple accounts, email search and drafting, and calendar event management.MIT
- AlicenseBqualityDmaintenanceMCP server for interacting with Google Gmail and Calendar via natural language, supporting multiple accounts.359MIT
- AlicenseNot gradedqualityCmaintenanceLocal MCP server for reading/sending email via Gmail and managing Google Calendar events, enabling an AI agent to handle email and calendar operations through natural language.MIT
- AlicenseNot gradedqualityDmaintenanceCustom MCP server for Gmail integration, enabling email listing, reading, searching, and sending via natural language.ISC