使用说明

项目简介

本项目是一个基于 Model Context Protocol (MCP) 构建的 Gmail 服务器，旨在为 LLM 客户端提供访问和操作 Gmail 邮箱的能力。通过此服务器，LLM 客户端可以安全地执行发送邮件、查看未读邮件、阅读邮件内容、删除邮件等操作，从而扩展 LLM 在邮件管理和自动化方面的应用场景。

主要功能点

邮件发送: 允许 LLM 客户端通过指定收件人、主题和内容来发送邮件。
未读邮件获取: 允许 LLM 客户端获取未读邮件列表，方便快速了解邮箱状态。
邮件内容读取: 允许 LLM 客户端根据邮件 ID 读取邮件的详细内容，包括发件人、收件人、主题和正文。
邮件标记已读: 允许 LLM 客户端将指定邮件标记为已读状态。
邮件移动到回收站: 允许 LLM 客户端将指定邮件移动到 Gmail 的回收站。
浏览器打开邮件: 允许 LLM 客户端在默认浏览器中打开指定的邮件，方便用户直接查看。

安装步骤

配置 Gmail API:
- 访问 Google Cloud Console 创建一个新的 Google Cloud 项目。
- 在项目中启用 Gmail API。
- 配置 OAuth 同意屏幕，选择 "外部"，并将您的个人邮箱地址添加到 "测试用户"。
- 添加 OAuth 作用域 'https://www.googleapis.com/auth/gmail/modify'，允许应用修改 Gmail 邮箱。
- 创建 "桌面应用" 类型的 OAuth 客户端 ID，并下载 JSON 格式的客户端密钥文件。
- 将下载的密钥文件重命名并保存到本地安全位置，记录文件路径。
克隆仓库:
- 将 GitHub 仓库 'https://github.com/jasonsum/gmail-mcp-server' 克隆到本地。
安装 uv (推荐):
- 按照 uv 官方文档安装 uv 包管理器 (非必须，也可以使用 pipenv, poetry 等)。

服务器配置

要将此 MCP 服务器配置到 MCP 客户端（例如 Claude Desktop），您需要提供服务器的启动命令和参数。以下是配置信息，请根据您的实际路径进行修改：

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": [
        "--directory",
        "[仓库绝对路径]",
        "run",
        "gmail",
        "--creds-file-path",
        "[Gmail API 凭据文件绝对路径]",
        "--token-path",
        "[Token 文件存储路径]"
      ]
    }
  }
}

参数说明:

'server name': 服务器名称，可以自定义，例如 'gmail'。
'command': 启动服务器的命令，这里推荐使用 'uv run gmail'，您需要确保 'uv' 命令可用。如果使用其他方式运行，请替换为相应的命令。
'args': 传递给服务器的参数列表：
- '--directory': '[仓库绝对路径]' - 请替换为克隆到本地的 'gmail-mcp-server' 仓库的绝对路径。
- 'run gmail': 使用 'uv run' 运行 'gmail' 模块 (对应 'src/gmail/init.py')。
- '--creds-file-path': '[Gmail API 凭据文件绝对路径]' - 请替换为您在 "Gmail API 配置" 步骤中下载并保存的 Gmail API 凭据 JSON 文件的绝对路径。
- '--token-path': '[Token 文件存储路径]' - 请替换为您希望存储 OAuth 访问令牌和刷新令牌的文件的绝对路径。首次运行时会自动创建。

注意:

'[仓库绝对路径]', '[Gmail API 凭据文件绝对路径]', '[Token 文件存储路径]' 都需要替换为实际的绝对路径。
Token 文件存储路径建议使用用户目录下的隐藏文件夹，例如 '/[your-home-folder]/.google/app_tokens.json'。

基本使用方法

启动 MCP 服务器：根据上述服务器配置，在 MCP 客户端中启动名为 'gmail' (或您自定义的服务器名称) 的 MCP 服务器。
授权 Gmail 访问：首次启动服务器时，会自动在浏览器中打开 Gmail 授权页面，请按照提示完成授权。授权成功后，访问令牌将自动保存到 '--token-path' 指定的文件中。
在 LLM 客户端中使用工具：服务器成功启动并连接到 MCP 客户端后，您可以在 LLM 客户端中使用以下工具来操作 Gmail：
- 'send-email': 发送邮件
- 'trash-email': 移动邮件到回收站
- 'mark-email-as-read': 标记邮件为已读
- 'get-unread-emails': 获取未读邮件列表
- 'read-email': 读取邮件内容
- 'open-email': 在浏览器中打开邮件
具体工具的使用方法和参数请参考仓库 README.md 文件中 "Components - Tools" 部分的描述。

关键词