Claude Code 通过 MCP 操作 Gmail 的完整指南 - 学习笔记-Claude Code-上海佼艾

一、MCP（Model Context Protocol）概览

MCP 是 Anthropic 推出的标准化协议，让 Claude Code 可以直接与外部工具和服务交互。通过 MCP，Claude Code 能够像调用内置工具一样操作 Gmail 邮箱，无需手动编写 Python 脚本或直接调用 API。

核心理念：MCP 将 Gmail 的功能封装为 Claude Code 可直接调用的"工具"。用户只需用自然语言下达指令（如"查看收件箱中来自张三的最新邮件"），Claude Code 就会自动调用 MCP 工具完成操作，无需编写任何代码。

1.1 MCP 的工作原理

MCP 采用客户端-服务器架构：

MCP 客户端：Claude Code 本身内置 MCP 客户端能力，可以发现和调用 MCP 服务器提供的工具
MCP 服务器：每个服务器封装特定服务的能力。Gmail MCP 服务器封装了邮件搜索、读取、发送等操作，暴露为标准化工具接口
通信协议：MCP 服务器通过 stdio（标准输入输出）或 HTTP 与 Claude Code 通信，传输 JSON-RPC 格式的请求和响应

与 Gmail API 方式的本质区别

前一篇文章介绍了通过 Python + Gmail API 操作 Gmail 的方式，与 MCP 方式的核心区别在于：

对比维度	Python + Gmail API	MCP 方式
操作方式	Claude Code 生成 Python 脚本，用户手动运行	Claude Code 直接在对话中调用 MCP 工具
代码编写	需要生成和运行代码	无需代码，自然语言指令即可
实时性	需要等待脚本运行完成	对话中即时返回结果
集成深度	需要手动处理认证、编码等	MCP 服务器自动处理认证
适用场景	复杂的自动化工作流、定时任务	即时查询、日常操作、快速交互

1.2 MCP 配置基础

MCP 服务器通过 Claude Code 的配置文件进行管理。配置文件位置：

全局配置：~/.claude/settings.json（对所有项目生效）
项目配置：项目根目录/.claude/settings.json（仅当前项目生效）
命令行管理：通过 claude mcp 系列命令管理

# MCP 服务器配置文件基本格式
{
    "mcpServers": {
        "服务器名称": {
            "command": "npx",
            "args": ["-y", "包名"]
        }
    }
}

# 通过命令行添加 MCP 服务器（推荐）
claude mcp add 服务器名称 -- npx -y 包名

MCP 的天然优势

MCP 方式的真正优势在于交互的自然性。你可以直接在对话中说"帮我查一下收件箱里昨天来自 HR 的邮件"，Claude Code 就能理解并调用相应的 MCP 工具完成操作。这种体验远超手动编写 Python 脚本的方式，尤其适合日常的快速查询和操作。

二、主流 Gmail MCP 服务器对比与选择

截至 2026 年，社区中有多款成熟的 Gmail MCP 服务器可供选择。它们在配置复杂度、功能范围和适用场景上各有侧重。

方案总览对比

方案	配置复杂度	功能覆盖	是否需要 Google Cloud	多账号	推荐场景
Google Workspace MCP	中等	12 项 Google 服务	是	支持	需要全功能 Google Workspace 集成
gmail-multi-mcp	低（零配置）	Gmail 核心功能	否（自动处理）	支持（多账号切换）	个人快速使用，多账号管理
gmail-autoauth-mcp	中低	Gmail 核心功能	是	单账号	需要精细控制权限范围
Composio	低（托管认证）	Gmail + 850+ 应用	否（第三方托管）	支持	需要多应用集成
Nylas	中等	多邮件提供商	否（第三方托管）	支持	需要跨平台邮件（Gmail+Outlook）
Coogle	低	12 项 Google 服务	是	支持（守护进程多路复用）	多会话并发操作 Google 服务

快速选择指南：

想最快上手、零配置 → 选 gmail-multi-mcp
需要全套 Google 服务（Gmail+Drive+Calendar+Docs） → 选 Google Workspace MCP
需要精细控制 OAuth 权限 → 选 gmail-autoauth-mcp
不想碰 Google Cloud 配置 → 选 Composio 或 gmail-multi-mcp
需要跨邮件提供商（Gmail + Outlook） → 选 Nylas

三、方案一：gmail-multi-mcp（零配置快速上手）

这是目前上手最快的 Gmail MCP 方案，无需 Google Cloud 项目，无需 API Key，一条命令即可完成配置。

3.1 安装步骤

# 第一步：添加 MCP 服务器到 Claude Code
claude mcp add gmail-multi -- npx -y @outfeedai/gmail-multi-mcp

# 第二步：重新启动 Claude Code
# 第三步：执行认证
npx -y @outfeedai/gmail-multi-mcp setup

# 浏览器会自动打开 Google OAuth 授权页面
# 登录你的 Google 账号并授权即可

多账号配置

gmail-multi-mcp 最大的特色是原生支持多账号。如果需要在工作和个人 Gmail 账号间切换，只需在 setup 时添加多个账号，在对话中直接告诉 Claude Code "切换到工作账号" 或 "查看我的个人邮箱" 即可。

3.2 提供的工具

工具名称	功能	使用示例
gmail_search	搜索邮件	"搜索来自 example.com 的未读邮件"
gmail_read	读取邮件内容	"打开最新那封邮件看看内容"
gmail_send	发送邮件	"给张三发一封邮件，主题是..."
gmail_draft	创建草稿	"帮我写一封回复草稿"
gmail_labels	管理标签	"给这封邮件加'重要'标签"
gmail_accounts	管理多账号	"切换到工作账号"

3.3 对话操作示例

用户："帮我查一下收件箱里最近 5 封未读邮件"

Claude Code（通过 MCP）：自动调用 gmail_search → 获取结果 → 展示邮件列表

用户："给小明发一封邮件，告诉他明天的会议改到下午 3 点"

Claude Code（通过 MCP）：自动调用 gmail_send → 构建邮件 → 发送 → 返回发送结果

认证存储

gmail-multi-mcp 将 OAuth token 存储在本地文件系统中，路径为 ~/.gmail-multi-mcp/。token 会自动刷新，无需手动干预。如果要撤销授权，只需删除该目录下的凭据文件即可。

四、方案二：Google Workspace MCP（全功能集成）

如果你需要的不仅仅是 Gmail，而是完整的 Google Workspace 集成（Gmail + Drive + Calendar + Docs + Sheets 等），Google Workspace MCP 是最佳选择。

4.1 前置条件

一个 Google Cloud 项目（访问 console.cloud.google.com 创建）
已启用以下 API：Gmail API、Google Drive API、Calendar API（按需启用）
已创建 OAuth 2.0 凭据（应用类型选择"桌面应用"或"Web 应用"）

OAuth 配置注意事项

如果选择"Web 应用"类型，需要在授权重定向 URI 中添加 http://localhost:8000/oauth2callback。如果选择"桌面应用"类型（PKCE 流程），则无需配置重定向 URI，配置更为简单。推荐大多数用户选择桌面应用类型。

4.2 安装配置

# 第一步：设置环境变量（从 Google Cloud 控制台获取）
export GOOGLE_OAUTH_CLIENT_ID="你的客户端ID"
export GOOGLE_OAUTH_CLIENT_SECRET="你的客户端密钥"

# 第二步：安装 uv（如果尚未安装）
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 第三步：添加 MCP 服务器（仅 Gmail 工具）
claude mcp add google-workspace -- uvx workspace-mcp --tools gmail

# 或者添加全部 Google 服务工具
claude mcp add google-workspace -- uvx workspace-mcp --tool-tier core

# 第四步：重启 Claude Code
# 首次使用时，Claude Code 会自动触发 OAuth 授权流程

4.3 核心工具列表

Google Workspace MCP 提供的 Gmail 相关工具：

工具分类	工具名称	功能说明
邮件搜索	gmail_list_messages	列出邮件，支持分页和搜索查询
	gmail_get_message	获取单封邮件详情（含正文和附件信息）
	gmail_search_messages	高级搜索，支持 Gmail 搜索语法
	gmail_get_thread	获取整个邮件线程的对话
邮件发送	gmail_send_message	发送新邮件（需二次确认）
邮件发送	gmail_reply_to_message	回复指定邮件
草稿管理	gmail_create_draft	创建草稿
草稿管理	gmail_update_draft	更新已有草稿
标签管理	gmail_list_labels	列出所有标签
	gmail_create_label	创建新标签
	gmail_modify_message	添加/移除标签，标记已读/未读
附件管理	gmail_get_attachment	下载附件
附件管理	gmail_send_with_attachment	发送带附件的邮件
垃圾邮件	gmail_report_spam	举报垃圾邮件

4.4 对话操作示例

// 搜索邮件示例（Claude Code 自动调用 MCP 工具）
// 用户说："帮我找一下上个月来自 HR 部门的所有邮件"
// Claude Code 内部调用：
gmail_search_messages(query: "from:hr@company.com after:2026/4/1 before:2026/5/1")

// 发送带附件邮件示例
// 用户说："把这份 report.pdf 发给经理，正文写'请查收季度报告'"
// Claude Code 内部调用：
gmail_send_with_attachment(
    to: "manager@company.com",
    subject: "季度报告",
    body: "请查收季度报告",
    file_path: "./report.pdf"
)

二次确认机制：Google Workspace MCP 默认对发送邮件操作启用了二次确认。Claude Code 在调用 gmail_send_message 之前，会先展示邮件内容供你确认，确认后才真正发送。这一设计有效防止了误操作。

五、方案三：gmail-autoauth-mcp（自主可控）

gmail-autoauth-mcp 是一个社区维护的 Gmail MCP 服务器，支持自动 OAuth 认证流程。适合需要自主控制 Google Cloud 项目和权限范围的用户。

5.1 安装步骤

# 第一步：准备 OAuth 凭据文件
# 在 Google Cloud Console 创建 OAuth 2.0 凭据（桌面应用类型）
# 下载 JSON 文件并重命名为 gcp-oauth.keys.json
mkdir -p ~/.gmail-mcp
# 将下载的 gcp-oauth.keys.json 放到 ~/.gmail-mcp/ 目录

# 第二步：执行一次性认证
npx @gongrzhe/server-gmail-autoauth-mcp auth

# 如果需要限制权限范围（推荐）
npx @gongrzhe/server-gmail-autoauth-mcp auth --scopes=gmail.readonly

# 第三步：添加到 Claude Code 配置
claude mcp add gmail -- npx @gongrzhe/server-gmail-autoauth-mcp

# 或者手动添加到 settings.json
{
    "mcpServers": {
        "gmail": {
            "command": "npx",
            "args": ["@gongrzhe/server-gmail-autoauth-mcp"]
        }
    }
}

5.2 支持的权限范围

Scope 参数	权限说明	适用场景
gmail.readonly	只读权限，可查看邮件但不能发送或修改	仅需查询和分析邮件的场景
gmail.modify	读写权限，可发送和管理邮件	日常使用（推荐）
gmail.send	仅发送邮件，不能读取	仅需自动发送通知的场景
gmail.labels	仅管理标签	只需要标签管理的场景

安全最佳实践

始终遵循最小权限原则：如果仅需读取邮件进行分析，使用 gmail.readonly 而非 gmail.modify。权限可以在后续随时升级，但一开始就给予过多权限会增加安全风险。

六、方案四：第三方托管方案（Composio / Nylas）

如果你不想直接管理 Google Cloud 项目和 OAuth 凭据，第三方托管服务可以帮你处理这些底层细节。

6.1 Composio 方案

Composio 是一个第三方 API 管理平台，提供了托管的 Gmail MCP 集成，无需设置 Google Cloud 项目。

# 安装 Python SDK
pip install composio-core

# 在 Composio 平台获取 API Key
# 然后生成 MCP URL 并添加到 Claude Code
claude mcp add gmail-composio --transport http <mcp-url> \
    --headers "x-api-key=<your-key>"

Composio 的优势

支持 850+ 应用集成，Gmail 只是其中之一
托管 OAuth 认证，无需自行管理凭据
内置速率限制处理、重试逻辑
支持多用户共享账号

6.2 Nylas 方案

Nylas 是一个邮件 API 平台，其 MCP 集成支持 Gmail、Outlook、Exchange 和 IMAP 等多种邮件提供商。

# Nylas MCP 配置
{
    "mcpServers": {
        "nylas": {
            "command": "npx",
            "args": ["@nylas/mcp-server"],
            "env": {
                "NYLAS_API_KEY": "你的API密钥",
                "NYLAS_API_URI": "https://api.us.nylas.com",
                "NYLAS_GRANT_ID": "你的授权ID"
            }
        }
    }
}

Nylas 的特色功能

统一接口：无论后端是 Gmail 还是 Outlook，MCP 工具接口完全一致
两步发送确认：发送邮件需要两次确认，防止误操作
日历集成：同时支持日历事件查询和创建
联系人管理：支持读取和搜索联系人

七、实战场景与对话示例

以下展示通过 MCP 方式操作 Gmail 的典型对话场景。所有操作均通过自然语言完成，Claude Code 自动调用底层的 MCP 工具。

7.1 场景一：收件箱管理

用户："查看我的收件箱，显示最近 10 封邮件的发件人和主题"

Claude Code：调用 gmail_list_messages / gmail_search_messages → 返回邮件列表

结果：显示 10 封邮件的发件人、主题、日期和摘要

用户："昨天有哪些未读邮件？帮我按时间排序"

Claude Code：调用 gmail_search_messages(query: "after:2026/5/3 is:unread") → 排序返回

7.2 场景二：邮件搜索与筛选

用户："搜索来自 github.com 且主题包含 'security alert' 的邮件"

Claude Code：调用 gmail_search_messages(query: "from:github.com subject:'security alert'") → 返回匹配邮件

用户："找出上个月所有带附件的发票邮件"

Claude Code：调用 gmail_search_messages(query: "after:2026/4/1 before:2026/5/1 has:attachment invoice") → 列出结果

7.3 场景三：邮件发送与回复

用户："给 zhangsan@company.com 发一封邮件，主题是'关于下周的会议安排'，正文告诉他会议定在周三下午两点"

Claude Code：先展示邮件预览 → 用户确认 → 调用 gmail_send_message → 发送成功

用户："回复刚才那封邮件，告诉他我会准时参加"

Claude Code：调用 gmail_reply_to_message → 构建回复 → 展示确认 → 发送

7.4 场景四：标签与分类

用户："创建一个名叫'项目 Alpha'的新标签，把所有来自 alpha-team@company.com 的邮件都加上这个标签"

Claude Code：调用 gmail_create_label → 搜索匹配邮件 → 调用 gmail_modify_message 逐一添加标签

7.5 场景五：多账号管理

用户："切换到我的个人 Gmail 账号"

Claude Code：调用 gmail_accounts(switch_to: "personal") → 切换完成

用户："把工作账号收件箱里今天的重要邮件转发到个人邮箱"

Claude Code：搜索工作账号邮件 → 获取内容 → 切换到个人账号 → 发送转发邮件

7.6 场景六：日常办公自动化

用户："帮我写一封每日站会的提醒邮件，发给整个团队，包含今天要讨论的三个议题：1）进度更新 2）阻塞问题 3）下一步计划"

Claude Code：生成邮件内容 → 展示预览 → 发送

用户："把上个月项目相关的所有邮件整理成一个摘要报告"

Claude Code：搜索项目相关邮件 → 读取内容 → 分析归纳 → 生成摘要报告 → （可选）通过 MCP 保存为文件

体验总结：MCP 方式的最大优势在于自然语言交互。相比于传统的 Gmail API 方式（需要编写 Python 代码 → 运行脚本 → 查看结果），MCP 方式只需在对话中描述需求，Claude Code 自动调用 MCP 工具完成操作，整个流程在对话中无缝完成。尤其适合日常办公中的快速查询和操作。

八、高级配置与多账号管理

8.1 配置文件详解

MCP 服务器的完整配置可以通过 JSON 文件进行精细控制：

// .claude/settings.json 完整配置示例
{
    "mcpServers": {
        // 方案一：gmail-multi-mcp（多账号，零配置）
        "gmail-multi": {
            "command": "npx",
            "args": ["-y", "@outfeedai/gmail-multi-mcp"],
            "env": {
                "GMAIL_MULTI_ACCOUNTS": "work,personal"
            }
        },
        // 方案二：Google Workspace MCP（全功能）
        "google-workspace": {
            "command": "uvx",
            "args": ["workspace-mcp", "--tools", "gmail"],
            "env": {
                "GOOGLE_OAUTH_CLIENT_ID": "xxx.apps.googleusercontent.com",
                "GOOGLE_OAUTH_CLIENT_SECRET": "xxx"
            }
        },
        // 方案三：gmail-autoauth-mcp（自主可控）
        "gmail": {
            "command": "npx",
            "args": ["@gongrzhe/server-gmail-autoauth-mcp"]
        }
    }
}

同时使用多个 MCP 服务器

Claude Code 可以同时加载多个 MCP 服务器，每个服务器提供不同的能力。例如，你可以同时配置 gmail-multi-mcp（处理个人 Gmail）和 google-workspace-mcp（处理工作账号的 Google 全套服务），在对话中 Claude Code 会自动选择合适的工具来完成任务。

8.2 环境变量配置

某些 MCP 服务器需要环境变量来传递配置信息。可以在 settings.json 的 env 字段中设置，也可以在系统环境中设置：

# 方式一：在 settings.json 中设置（推荐）
{
    "mcpServers": {
        "google-workspace": {
            "command": "uvx",
            "args": ["workspace-mcp"],
            "env": {
                "GOOGLE_OAUTH_CLIENT_ID": "你的客户端ID",
                "GOOGLE_OAUTH_CLIENT_SECRET": "你的客户端密钥"
            }
        }
    }
}

# 方式二：系统环境变量（适用于 CI/CD 或服务器环境）
export GOOGLE_OAUTH_CLIENT_ID="你的客户端ID"
export GOOGLE_OAUTH_CLIENT_SECRET="你的客户端密钥"

8.3 MCP 命令管理

# 列出所有已配置的 MCP 服务器
claude mcp list

# 查看某个 MCP 服务器的详细信息
claude mcp get gmail

# 添加新的 MCP 服务器
claude mcp add 服务器名称 -- 启动命令 参数

# 移除 MCP 服务器
claude mcp remove gmail

# 测试 MCP 服务器连接
claude mcp test gmail

九、安全与权限管理

通过 MCP 操作 Gmail 涉及邮箱的读写权限，安全问题是重中之重。

9.1 权限范围选择

OAuth 范围	允许的操作	风险等级
gmail.readonly	读取邮件、搜索、获取附件元数据	低
gmail.send	仅发送邮件	中
gmail.modify	读写、发送、管理标签、标记已读/未读	中高
mail.google.com（完全访问）	所有操作，包括永久删除	高

最小权限原则：始终只授予完成任务所需的最小权限。例如，如果只需要搜索和阅读邮件，使用 gmail.readonly 而不是 gmail.modify。很多 MCP 服务器在安装时允许指定权限范围。

9.2 Token 安全管理

本地存储：OAuth token 存储在本地文件系统（如 ~/.gmail-mcp/、~/.google_workspace_mcp/），不会上传到云端
自动刷新：MCP 服务器自动处理 token 刷新，无需手动干预
撤销授权：可在 Google 账号的安全设置中随时撤销对 MCP 服务器的授权
文件保护：确保 token 存储目录的权限设置正确，不被其他用户读取

9.3 发送确认机制

大多数 Gmail MCP 服务器实现了发送确认机制：

Claude Code 在调用发送工具前，会先展示邮件预览（收件人、主题、正文）
用户确认后才真正执行发送
部分 MCP 服务器（如 Nylas）实现了两步确认，进一步降低误操作风险

安全使用检查清单

只使用 gmail.readonly 范围，除非确实需要发送或修改邮件
定期检查 Google 账号的安全设置，查看已授权的第三方应用
不要在共享电脑上保存 token，或确保 token 文件权限正确
不使用时可以暂时禁用 MCP 服务器（通过 claude mcp remove 或注释配置）
离职或不再需要时，及时撤销 OAuth 授权

十、常见问题与故障排除

问题	原因	解决方案
claude mcp add 后找不到工具	MCP 服务器未正确加载	重启 Claude Code；运行 `claude mcp list` 检查状态；重新添加
OAuth 认证时浏览器页面空白	端口被占用或防火墙拦截	关闭冲突进程；检查防火墙设置；尝试指定其他端口
发送邮件时返回权限错误	OAuth 范围不包含发送权限	重新认证时使用 gmail.modify 或 gmail.send 范围
"MCP server exited unexpectedly"	Node.js 版本不兼容或依赖缺失	升级 Node.js 到 18+；重新安装 MCP 包；检查网络连接
Token 过期/失效	OAuth token 自然过期或手动撤销	删除 token 文件后重新执行认证流程
中文邮件内容乱码	MCP 服务器的编码处理问题	确保使用最新版本的 MCP 服务器；在邮件中明确设置 charset=utf-8
搜索不到已存在的邮件	Gmail 搜索索引延迟或搜索范围不对	检查搜索语法；确认邮件不在垃圾箱或归档中
多账号切换不生效	MCP 服务器配置未更新	重启 Claude Code；重新运行 setup；检查账号列表
uvx command not found	未安装 uv 工具	安装 uv：curl -LsSf https://astral.sh/uv/install.sh \| sh
npx 运行极慢或无响应	网络问题导致 npm 包下载缓慢	检查网络连接；配置 npm 镜像源；使用代理

日志与调试

# 查看 MCP 服务器日志（有助于排查问题）
# Claude Code 通常在以下位置记录 MCP 相关日志：
# macOS/Linux: ~/.claude/logs/
# Windows: %USERPROFILE%\.claude\logs\

# 测试 MCP 服务器是否能正常启动
npx -y @outfeedai/gmail-multi-mcp

# 测试 Google Workspace MCP
uvx workspace-mcp --tools gmail

排错第一步

遇到 MCP 连接问题时，首先运行 claude mcp list 检查服务器状态。如果显示 disconnected 或 error，尝试 claude mcp remove 服务器名 后重新添加。大多数问题都可以通过重启 Claude Code + 重新添加 MCP 服务器解决。

十一、MCP 方式 vs API 方式：选型建议

现在我们已经全面掌握了两种操作 Gmail 的方式。以下是两者的对比总结和场景选择建议。

对比维度	MCP 方式（本文）	Python + Gmail API（上篇）
交互方式	自然语言对话，即时操作	编写并运行 Python 脚本
学习成本	低，仅需配置一次性环境	中，需要了解 Gmail API 和 Python
配置复杂度	低（gmail-multi-mcp）到中（Google Workspace MCP）	中（需要 Google Cloud 配置）
实时性	高，对话中即时返回	中，需等待脚本运行
自动化能力	弱，依赖用户主动发起	强，可配置定时任务、批量处理
可编程性	弱，受限于 MCP 服务器提供的工具	强，可自由组合 API 接口
适用场景	日常查询、快速操作、即时回复	批量处理、定时任务、复杂工作流
安全模型	MCP 服务器管理 OAuth，发送需确认	自行管理凭据，完全可控

场景选择建议

日常办公（查看邮件、快速回复）→ MCP 方式
批量处理（备份所有附件、清理旧邮件）→ API 方式
集成到现有系统（自动发送报表、定时任务）→ API 方式
快速原型验证→ MCP 方式
复杂分析（邮件内容分析、分类统计）→ 两者结合：MCP 搜索提取 + API 批量处理

事实上，两种方式并不互斥。你可以在日常工作中使用 MCP 方式快速操作，同时在需要自动化时使用 Gmail API 编写脚本。Claude Code 同时支持这两种工作模式。

核心要点总结

MCP 是让 Claude Code 直接操作 Gmail 的最佳方式：无需编写代码，通过自然语言对话即可完成邮件搜索、读取、发送、标签管理等操作。
gmail-multi-mcp 是最快的入门方案：零配置、无需 Google Cloud 项目，一条命令即可开始使用，且原生支持多账号管理。
Google Workspace MCP 功能最全面：如果需要同时操作 Gmail、Drive、Calendar 等多个 Google 服务，这是最佳选择。
gmail-autoauth-mcp 提供精细权限控制：适合需要明确指定 OAuth 权限范围的场景。
第三方托管方案适合不想管理 OAuth 的用户：Composio 和 Nylas 帮您处理所有认证和基础设施。
安全永远是第一位：遵循最小权限原则，定期检查已授权的应用，使用发送确认机制防止误操作。
MCP 与 API 方式互补：日常操作用 MCP，批量自动化用 API，两者结合可覆盖所有场景。