AI导哈

Gmail读取服务器

一个基于Model Context Protocol (MCP)的服务器，为AI助手提供只读的Gmail访问功能，包括邮件列表、搜索、读取和附件管理。

  • by wrxck
  • Java
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 wrxck/gmail-mcp

使用说明

Gmail MCP服务器

A. 模型上下文协议 （MCP）服务器，为AI助手提供只读的Gmail访问权限，如 克劳德代码.内置Java 21使用官方 MCP Java SDK.

特性

工具 说明
list_emails 使用可选查询和标签过滤器列出最近的电子邮件
read_email 通过邮件ID读取电子邮件的完整内容（包括附件元数据）
search_emails 使用搜索电子邮件 Gmail搜索语法
get_attachment 根据邮件ID和附件索引获取附件内容
list_labels 列出所有Gmail标签

所有访问权限均为 只读 (GMAIL_READONLY 范围）。服务器无法发送、修改或删除电子邮件。

附件是通过以下方式发现的 read_email （其中包括 attachments 带有元数据的数组），并通过以下方式单独获取 get_attachment:

  • 文本附件 (text/*)内联返回解码内容
  • 图片附件 (image/*，最多10MB）以内联方式返回 ImageContent 用于视觉分析
  • 其他二进制附件 （PDF、文档等）保存到 ~/.gmail-mcp/attachments/<messageId>/ 并返回文件路径

先决条件

  • Java 21+
  • Maven 3.6+
  • 启用Gmail API的谷歌云项目
  • OAuth 2.0凭据（桌面应用程序类型）

设置

1.谷歌云凭据

  1. 去 Google 云控制台
  2. 创建项目（或选择现有项目）
  3. 启用 Gmail API 在API和服务下
  4. 首选 凭证 > 创建凭据 > OAuth客户端ID
  5. 选择 桌面应用程序 作为应用程序类型
  6. 下载JSON文件并将其另存为 ~/.gmail-mcp/client_secret.json

2.建造

git clone https://github.com/wrxck/gmail-mcp.git
cd gmail-mcp
mvn clean package

这会产生一个超级罐子 target/gmail-mcp-1.3.0.jar.

3.身份验证

java -jar target/gmail-mcp-1.3.0.jar --auth

这将打开您的浏览器以获得Google OAuth同意。授权后，凭据将保存到 ~/.gmail-mcp/tokens/ 并在到期时自动刷新。你只需要做一次。

4.用克劳德代码注册

claude mcp add --scope user --transport stdio gmail -- \
  java -jar /path/to/gmail-mcp-1.3.0.jar

重新启动克劳德代码。4个Gmail工具将立即可用。

用法示例

一旦注册，你可以问克劳德：

  • “查看我最近的电子邮件”
  • “搜索来自的电子邮件john@example.com关于项目建议书”
  • “阅读电子邮件 <message-id>"
  • “我有什么标签？”
  • “在我的收件箱中查找本周以来的未读电子邮件”

安全

电子邮件内容是不受信任的第三方数据，直接返回到LLM的上下文中。恶意电子邮件可能包含旨在操纵代理采取意外行动的文本。此服务器应用了深度防御缓解措施：

  • 随机内容边界 --每个工具响应都会生成一个加密随机的边界字符串（通过 SecureRandom).不受信任的字段(from, subject, snippet, body, filename, content)用这个边界包裹，这样LLM就可以区分电子邮件数据和系统结构。由于边界是不可预测的，攻击者无法将其嵌入电子邮件中以逃离内容区域。
  • 安全背景序言 --每个电子邮件工具响应都包含一个前导文本块，解释边界标记并指示LLM将有界内容仅视为数据。
  • 工具描述警告 --The list_emails, read_email, search_emails，以及 get_attachment 工具说明明确警告返回的内容不受信任。
  • 车身截断 --超过50000个字符的电子邮件正文将被截断 [TRUNCATED] 指示器，以防止超大有效载荷压倒上下文。附件内容被截断为100000个字符。
  • 类型化附件处理 — text/* 附件内联返回解码内容。 image/* 附件（最大10 MB）将作为返回 ImageContent 用于视觉分析。所有其他二进制附件都保存到 ~/.gmail-mcp/attachments/ 使用经过净化的文件名，并返回文件路径。对电子邮件中的文件名进行净化，以防止路径遍历攻击。

建筑

Claude Code  <--stdio (JSON-RPC)-->  gmail-mcp.jar  <--HTTPS-->  Gmail API
                                          |
                                    ~/.gmail-mcp/
                                      client_secret.json
                                      tokens/StoredCredential
  • 运输：stdio（Claude Code将服务器作为子进程生成）
  • OAuth: GoogleAuthorizationCodeFlow 随着 FileDataStoreFactory 处理令牌持久性和自动刷新
  • 日志记录：所有日志都转到stderr（stdout保留给MCP JSON-RPC）

配置

凭据存储在 ~/.gmail-mcp/ 具有受限权限(rwx------):

~/.gmail-mcp/
  client_secret.json    # OAuth client credentials (you provide this)
  tokens/               # Stored OAuth tokens (auto-managed)
    StoredCredential
  attachments/           # Saved binary attachments (auto-managed, rwx------)
    <messageId>/
      <sanitized-filename>

发展

# Build
mvn clean package

# Run tests
mvn test

# Run auth flow
java -jar target/gmail-mcp-1.3.0.jar --auth

# Run server (blocks on stdio — use with Claude Code or an MCP client)
java -jar target/gmail-mcp-1.3.0.jar

项目结构

src/main/java/com/gmail/mcp/
  GmailMcpServer.java    # Main class, MCP tool definitions
  GmailAuth.java          # OAuth flow, credential management
  GmailClient.java        # Gmail API wrapper
  ContentSanitizer.java   # Prompt injection mitigations

src/test/java/com/gmail/mcp/
  ContentSanitizerTest.java    # Boundary wrapping, truncation, sanitization
  ResponsePipelineTest.java    # End-to-end response pipeline (email vs label tools)
  GmailClientTest.java         # HTML stripping, base64 decoding, body extraction
  GmailMcpServerTest.java      # Argument parsing

许可证

麻省理工学院

相关 MCP