使用说明

项目简介

Gmail MCP 是一个遵循 Model Context Protocol (MCP) 标准的服务器实现。它允许 MCP 兼容的客户端（例如支持 MCP 的大型语言模型 AI 助手）通过标准化的接口访问和操作用户的 Gmail 邮箱。这个服务器充当了 AI 助手与 Gmail API 之间的桥梁，将复杂的邮件操作封装成易于 AI 理解和调用的“工具”。

主要功能点

发送邮件: AI 助手可以调用工具发送新的电子邮件。
创建下草稿: 支持创建邮件草稿，方便后续编辑或发送。
阅读和搜索邮件: 允许 AI 助手获取指定邮件的详细内容，或根据关键词、条件搜索收件箱中的邮件。
删除邮件: 可以根据邮件 ID 删除指定的邮件。
管理标签: 提供创建、更新、删除和列出 Gmail 标签的功能，帮助组织和分类邮件。
安全认证: 通过 OAuth2.0 协议与 Google Gmail API 进行身份验证，确保安全访问用户数据。

安装步骤

克隆仓库: 将项目代码下载到本地计算机。

git clone https://github.com/ykuchiki/gmail-mcp.git
cd gmail-mcp

安装依赖: 使用 'uv'（推荐）或 'pip' 安装项目所需的库。

# 使用 uv
uv init
uv pip install -r requirements.txt

# 或者使用 pip
# python -m venv .venv
# source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate   # Windows
# pip install -r requirements.txt

配置 Gmail API OAuth 凭据:
- 前往 Google Cloud Console 创建一个新项目。
- 在该项目中启用 Gmail API。
- 创建 OAuth 客户端 ID 凭据。
- 在 OAuth 凭据设置中，将 'http://localhost:8080/' 添加到授权的重定向 URI 列表中。
- 下载生成的 JSON 凭据文件，将其保存到项目根目录下的 'credentials' 文件夹中，并命名为 'client_secret_gmail_oauth.json'。如果 'credentials' 文件夹不存在，请先手动创建。
首次运行进行认证: 第一次运行服务器时，会启动一个本地网页服务，引导您使用 Gmail 账号登录并授权应用访问您的 Gmail 数据。完成授权后，凭据将被保存供后续使用。

服务器配置 (用于 MCP 客户端)

要让您的 MCP 客户端能够连接并使用此 Gmail MCP 服务器，您需要在客户端的配置中添加一个服务器入口。配置通常是一个 JSON 结构，告知客户端如何启动和连接 MCP 服务器进程。

配置示例（非代码，请参考您的 MCP 客户端文档进行实际配置）：

服务器名称: 您可以为这个服务器指定一个在客户端内显示的名称，例如 'gmail-mcp'。
命令 (command): 启动服务器进程的命令，通常是您用来执行 Python 脚本的命令，例如 'uv' 或 'python'。
参数 (args): 传递给命令的参数列表。对于此项目，参数通常是指定运行脚本的目录和主文件：'--directory <您的项目路径>/src run main.py' (使用 uv) 或 '<您的项目路径>/src/main.py' (使用 python)。请务必将 '<您的项目路径>' 替换为您实际克隆 'gmail-mcp' 仓库的路径。
传输协议 (transport): 此服务器默认使用 'stdio' 传输协议，这是 MCP 客户端启动子进程时常用的方式。通常无需在客户端配置中显式指定，客户端默认会使用 stdio。

完成客户端配置后，当 AI 助手需要访问 Gmail 功能时，客户端将根据配置启动 Gmail MCP 服务器进程，并通过 MCP 协议与之通信。

基本使用方法

此服务器是为 MCP 兼容的 AI 助手或客户端设计的后端服务。您无需直接与服务器进程交互（除了首次运行进行认证）。一旦服务器配置正确并启动，您的 AI 助手将能够识别并调用服务器提供的 Gmail 相关工具（例如，当您指示 AI 发送邮件时，AI 助手会通过 MCP 客户端调用 'send_email' 工具）。

关键词