Gmail MCP 服务器

使用说明（Markdown格式）

• 项目简介

  • 该仓库实现了一个基于 MCP（Model Context Protocol）的服务器端，用于向大型语言模型（LLM）客户端提供 Gmail 相关的上下文信息、工具接口与提示模板。核心功能包括：托管和管理资源（如标签、邮箱信息等）、注册并执行工具（如发送邮件、读取邮件、搜索等 Gmail 操作）、以及定义和渲染提示模板，便于 LLM 进行对话和操作。

• 主要功能点

  • MCP 核心实现：通过 @modelcontextprotocol/sdk 架构创建并启动 MCP 服务器，注册 ListTools（获取可用工具）与 CallTool（执行具体工具）的请求处理器，符合 MCP 的请求-响应模式。
  • 工具体系：提供丰富的 Gmail 相关工具（发送/草稿/读取/搜索邮件、修改/删除邮件、处理标签、过滤器等），并将工具定义转换为 MCP 端可使用的格式，支持参数校验与错误处理。
  • 安全与认证：内置 OAuth2 流程支持 Gmail API 访问，包含凭证加载、授权回调、凭证保存等机制。
  • Gmail API 封装：封装 Gmail API 调用的各类操作，提供读取邮件、搜索、标签管理、过滤器等能力，并对异常进行统一封装。
  • 本地化通信传输：默认使用标准输入输出（Stdio）传输与 MCP 服务端通信，便于在开发环境中进行与 LLM 的交互。

• 安装步骤

  1. 克隆仓库并进入项目目录。安装依赖，例如通过 npm install 来安装 Node.js 依赖。
  2. 构建项目：执行构建命令，将 TypeScript 源代码编译为可执行的 dist/index.js。
  3. 进行 Gmail OAuth2 授权：
     • 按照项目要求准备 gcp-oauth.keys.json（包含 Gmail API 的 OAuth 客户端密钥）。
     • 运行认证流程以获取并保存 credentials.json，用于后续对 Gmail 的访问授权。
  4. 启动 MCP 服务器：执行构建产物的启动命令，服务器将读取凭证并开启与 MCP 客户端的通信。
  5. 可选：按需配置在 IDE/工具中的 MCP 连接设置，通过 setup-mcp.js 提供的自动化脚本生成本地配置。

• 服务器配置（针对 MCP 客户端，非客户端需要的配置信息，以下信息用于帮助集成与自动化） 说明：MCP 客户端不需要直接运行此配置，但某些 IDE、工具链可能需要将该信息用于自动化连接。配置示例（JSON 结构，含 serverName、command、args 等字段）如下，解释性注释在后面： { "serverName": "gmail", // MCP 服务器在本地/工作区的标识名（在代码中为 Gmail MCP 服务的实例别名） "command": "node", // 启动服务器的命令 "args": ["dist/index.js"] // 启动命令的参数，指向构建产物入口 } 注释说明：

  • serverName 对应在仓库中通过 setup-mcp.js 生成的配置中的 Gmail 服务器标识名。
  • command 与 args 组合用于在开发环境中通过进程启动 MCP 服务器。
  • 客户端实际使用时并不需要读写该配置文件，配置仅用于开发环境的自动化集成与 IDE 适配。

• 基本使用方法

  • 认证与授权：首次使用需完成 Gmail OAuth2 授权流程，获取凭证后服务器方可正常访问 Gmail API。
  • 启动服务器：在构建成功后直接运行生成的 dist/index.js，服务器将启动并通过标准输入输出（Stdio）与 MCP 客户端建立通信。
  • 调用工具：通过 MCP 客户端（如集成到你的 LLM 工作流中）向服务器发起 ListTools 请求以获取可用工具，再用 CallTool 请求执行具体工具（如发送邮件、读取邮件等）。
  • 错误处理与日志：服务器端对常见错误提供明确的错误信息，便于调试与排错。

• 其他注意

  • 服务器使用 Gmail API，因此需要有效的 Gmail OAuth2 凭据。
  • 工具参数通过 Zod 校验，确保输入结构正确，提升鲁棒性。