Skip to main content
Glama
lite-google-workspace-mcp

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

前置条件

  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 个工具)

工具

描述

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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server to interact with Google Gmail and Calendar APIs. Supports multiple accounts, email search and drafting, and calendar event management.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server for interacting with Google Gmail and Calendar via natural language, supporting multiple accounts.
      35
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Custom MCP server for Gmail integration, enabling email listing, reading, searching, and sending via natural language.
      ISC