Gmail MCP Server for Claude Code

使用说明内容（Markdown格式）

• 项目简介 该项目实现一个基于 MCP 的本地服务器，用于控制 Gmail。提供对邮箱资源的读取、搜索、发送、草稿、标签等功能，以及用于 Claude Code 等 LLM 客户端的工具调用接口，支持在本地直接连接 Gmail API 并进行授权后使用。

• 主要功能点

  • 资源与数据访问：查询账户信息、搜索邮件、读取邮件与线程、获取草稿、列出标签等，作为上下文与数据源的支撑。
  • 工具集成（14 个工具）：gmail_get_profile、gmail_search、gmail_read_message、gmail_read_thread、gmail_send、gmail_reply、gmail_forward、gmail_create_draft、gmail_send_draft、gmail_list_drafts、gmail_delete_draft、gmail_trash、gmail_modify_labels、gmail_list_labels。
  • 邮件操作能力：完整的发送、回复、转发、草稿管理、标签管理等，支持正确的邮件线程和头信息设定。
  • 安全与认证：使用 OAuth2 流程进行 Gmail API 授权，需配置并保存 .gmail_credentials.json 与 .gmail_token.json，支持令牌刷新。
  • MCP 服务器实现：通过 mcp 包提供的服务器、工具注册与调用能力，支持 stdio 或其他传输模式下的 JSON-RPC 风格请求/响应。
  • 本地化部署：可在本地部署并通过 Claude Code 等 MCP 客户端进行调用，避免将敏感账号信息暴露在云端。

• 安装步骤

  • 安装依赖：
    • pip install 'mcp[cli]' google-auth-oauthlib google-api-python-client
  • 获取并放置 Google Gmail OAuth 证书：
    • 将 Google Cloud OAuth 客户端密钥保存为 .gmail_credentials.json，放在脚本同一目录。
  • 进行首次授权：
    • 运行 python gmail_setup.py，浏览器会打开完成授权并生成 .gmail_token.json。
  • 运行并接入 Claude Code：
    • 安装并配置好本仓库中的 Gmail MCP 服务器脚本，启动后将 Gmail 的 MCP 服务配置到 Claude Code 的 MCP 配置中（示例见下方配置）。
  • 配置文件位置：
    • 项目根目录下的 .mcp.json 是示例配置，Claude Code 读取该配置来连接 MCP 服务器。

• 服务器配置（MCP 客户端需要的配置，不是服务器端） 配置示例（请根据实际路径替换为真实路径）: { "mcpServers": { "gmail": { "command": "python", "args": ["gmail_server.py"], "cwd": "/path/to/gmail-claude-code-suite" } } }

  说明: 该配置用于告知 MCP 客户端如何启动并连接本地 Gmail MCP 服务器。MCP 客户端不需要此段代码，仅需按上述格式提供信息即可建立连接。

• 基本使用方法

  • 启动授权流程：在仓库目录执行 python gmail_setup.py，浏览器完成 Gmail 授权，token 文件将保存到本地。
  • 在 Claude Code 中添加 MCP 服务：将上面的配置用于 Claude Code 的 MCP 设置，使其能够发现并向 Gmail 服务发送工具调用请求。
  • 调用工具：通过 Claude Code 的对话接口，发起对 Gmail 工具的请求（如搜索、读取、发送等），服务器将返回标准化的 JSON-RPC 风格响应。
  • 注意事项：确保 Gmail API 的授权范围与服务器需求匹配（gmail.modify、gmail.settings.basic），并处理好令牌刷新与权限问题。

• 额外信息

  • 该实现包含 Gmail API 的各种工具函数，能够完成大多数日常邮箱操作需求，且通过 MCP 工具注册机制暴露到客户端。
  • 部署后，请确保本地网络环境与 Google 账号授权状态正常，以避免令牌失效或权限变更导致的请求失败。