Gmail MCP Server

什么是 Gmail MCP Server？

Gmail MCP Server 是一个由社区开发、使用 Python 编写的小型 Gmail MCP 服务器，可让 Claude Desktop 等 MCP 客户端通过 Gmail API 读取你最近的收件箱邮件并搜索邮件，采用 OAuth2 认证且仅申请只读权限。

该项目由 GitHub 用户 ajbr0wn 创建（源码：github.com/ajbr0wn/gmail-mcp-server），并非 Google 官方出品。它只提供一个资源和一个工具，无法发送、删除邮件或添加标签。如果你只想让 AI 助手在邮箱里查找信息，这是一个范围小、风险低的选择。

如何使用 Gmail MCP Server？

该服务器在本地通过 stdio 运行。你需要 Python 3.12（README 使用 conda 环境）、一个 Google Cloud 项目，以及一个用于 Gmail API 的 OAuth 客户端。它没有发布到 PyPI，因此需要从仓库克隆后安装。

1. 创建 Google OAuth 凭据

1. 在 Google Cloud Console 创建项目。
2. 启用 Gmail API。
3. 创建 OAuth 2.0 凭据，应用类型选择 Desktop application。
4. 下载文件并保存为 credentials.json。

2. 安装服务器

git clone https://github.com/ajbr0wn/gmail-mcp-server.git
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail
cd gmail-mcp-server
pip install -e .

3. 设置两个必需的环境变量

• GMAIL_CREDENTIALS_FILE：Google OAuth 凭据文件的路径
• GMAIL_TOKEN_FILE：认证令牌的保存路径（首次登录时自动创建）

在接入客户端之前，可以先直接运行测试：

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

Claude Desktop

将以下内容添加到 claude_desktop_config.json，并把所有 /path/to/ 替换为实际路径：

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

重启 Claude Desktop。Claude 第一次访问 Gmail 时会打开浏览器窗口让你授权应用；之后令牌会保存到 GMAIL_TOKEN_FILE 并自动刷新。

Claude Code

README 只记录了 Claude Desktop 的配置，但任何 stdio 客户端都可以用同样的命令和环境变量启动它。在 Claude Code 中：

claude mcp add gmail \
  -e PYTHONPATH=/path/to/gmail-mcp-server/src \
  -e GMAIL_CREDENTIALS_FILE=/path/to/credentials.json \
  -e GMAIL_TOKEN_FILE=/path/to/token.json \
  -- /path/to/conda/envs/mcp-gmail/bin/python -m gmail_mcp_server.server

对于 Cursor、VS Code 等其他客户端，在其 MCP 配置文件中复用上面 Claude Desktop 配置里的 command、args 和 env 即可。

Gmail MCP Server 的主要功能

• 通过 gmail://inbox/recent 资源读取收件箱中最近的 10 封邮件。
• 使用 Gmail 标准搜索语法（from:、after:、subject: 等）搜索邮件。
• 仅申请 Gmail 只读权限，不请求任何写入权限。
• 首次使用时在浏览器中进行 OAuth2 登录，之后自动刷新令牌。
• 凭据和令牌保存在你指定的本地文件中。
• 向 stderr 输出详细日志，涵盖启动、认证、资源与工具调用以及错误信息。
• Python 代码量小，易于阅读和扩展。

Gmail MCP Server 工具

该服务器只有一个工具和一个资源：

• search_emails 接收必填的 query（任意 Gmail 搜索字符串）和可选的 max_results（默认 10）。可用于按发件人、日期范围、主题或标签查找邮件。
• gmail://inbox/recent 资源不是工具；支持 MCP 资源的客户端可以附加它，把你最新的 10 封邮件作为上下文提供给模型。

没有用于发送、起草、归档或删除邮件的工具。

Gmail MCP Server 的使用场景

• 不离开助手即可快速查看收件箱：“我最近的邮件都在说什么？”
• 查找特定邮件：“Could you show me any emails from sanrio in the last two days?”（README 自带的示例）
• 从收据或确认邮件中提取信息：“搜索本月航空公司发来的邮件，并列出预订编号。”
• 汇总同一发件人的更新：“查找本周 GitHub 关于构建失败的邮件并总结。”
• 为编程或写作任务提供邮件上下文，例如在别处起草回复前先查阅客户的 bug 报告。

Gmail MCP Server 与替代方案对比

• Google 的 Gmail MCP 服务器： Google 在 Google Workspace Developer Preview Program 中提供远程 Gmail MCP 端点 https://gmailmcp.googleapis.com/mcp/v1（配置指南）。它使用 Streamable HTTP 和 OAuth 2.0，工具包括 search_threads、get_thread、create_draft 以及标签管理。如果你需要由 Google 托管、还能创建草稿的服务器，选择它；如果你想要无需加入预览计划的本地只读方案，选择这个 Gmail MCP 服务器。
• 功能更完整的社区服务器： 其他开源 Gmail MCP 服务器增加了发送、标签和附件等功能。它们的权限范围更大，连接真实邮箱前请先审查其申请的权限。

Gmail MCP Server 常见问题排查

• ModuleNotFoundError: gmail_mcp_server： 客户端使用了另一个 Python。把 command 指向 mcp-gmail 环境中的解释器，并将 PYTHONPATH 设置为仓库的 src 目录。
• 启动失败： 确认 GMAIL_CREDENTIALS_FILE 和 GMAIL_TOKEN_FILE 都已设置；README 将两者都标为必需。请使用完整路径，而不是占位符。
• 没有弹出浏览器或授权报错： 确认 OAuth 客户端类型为 Desktop application，并且 Gmail API 已在凭据所属的同一个 Google Cloud 项目中启用。
• 需要重新授权或切换账号： 在 Google 账号设置中撤销访问权限，删除令牌文件后重新运行，即可触发新的登录。
• 原因不明的失败： 查看服务器的 stderr 输出；服务器会在那里记录认证状态和错误。