使用说明

项目简介

MCP Gmail服务器是一个实现了模型上下文协议（Model Context Protocol, MCP）的后端应用，它允许大型语言模型（LLM）安全且方便地访问用户的Gmail邮箱。通过此服务器，LLM可以读取邮件、发送邮件、搜索邮件以及管理邮件标签等，从而扩展LLM在邮件处理和信息检索方面的能力。

主要功能点

邮件资源访问: 将Gmail邮件和邮件线程作为MCP资源进行管理，允许LLM通过标准化的资源URL访问邮件内容。
邮件操作工具: 提供一系列工具，使LLM能够执行邮件的撰写、发送、搜索、标记已读、添加/移除标签等操作。
OAuth 2.0 认证: 使用安全的OAuth 2.0协议与Google Gmail API进行认证，保障用户数据安全。
灵活配置: 支持通过环境变量灵活配置服务器端口、OAuth凭据路径等参数。

安装步骤

环境准备: 确保已安装 Python 3.10+ 环境。推荐使用 'uv' 进行Python包管理以获得更好的性能。
安装依赖: 在仓库根目录下，使用 'uv' 安装项目依赖。
```
uv sync
```
配置Gmail API OAuth凭据:
- 访问 Google Cloud Console 并创建一个新的Google Cloud项目。
- 在项目中启用 Gmail API。
- 配置 OAuth 同意屏幕，填写应用信息并选择 “外部” 用户类型。
- 创建 OAuth 客户端ID，选择 “桌面应用” 类型，并下载JSON格式的凭据文件 ('credentials.json')，将其保存到项目根目录。
- 在 OAuth 同意屏幕中，添加 Gmail API 的 '.../auth/gmail.modify' 范围，以授予应用读写Gmail的权限。

运行服务器:

开发模式 (推荐): 使用 'uv' 运行开发服务器：

uv run mcp dev mcp_gmail/server.py

Claude Desktop 集成: 如果您使用 Claude Desktop，可以使用以下命令安装并运行MCP服务器：

uv run mcp install \
    --with-editable . \
    --name gmail \
    --env-var MCP_GMAIL_CREDENTIALS_PATH=$(pwd)/credentials.json \
    --env-var MCP_GMAIL_TOKEN_PATH=$(pwd)/token.json \
    mcp_gmail/server.py

服务器配置

MCP服务器需要配置后才能被MCP客户端（例如 Claude Desktop）调用。以下是配置 MCP Gmail 服务器的 JSON 格式配置信息，您需要将其添加到 MCP 客户端的服务器配置中。

{
  "servers": {
    "gmail": {  // 服务器名称，客户端通过此名称引用
      "command": "uv", // 启动服务器的命令，这里使用 uv
      "args": [  // 启动命令的参数列表
        "run",
        "mcp",
        "install",
        "--with-editable",
        ".",
        "--name",
        "gmail",
        "--env-var",
        "MCP_GMAIL_CREDENTIALS_PATH=$(pwd)/credentials.json", // Gmail OAuth 凭据文件路径
        "--env-var",
        "MCP_GMAIL_TOKEN_PATH=$(pwd)/token.json",  // OAuth Token 存储路径
        "mcp_gmail/server.py" // 服务器启动脚本路径
      ]
    }
  }
}

注意:

请确保 'credentials.json' 和 'token.json' 文件路径配置正确。
如果您在使用 Claude Desktop 时遇到 'Error: spawn uv ENOENT' 错误，可能需要在 Claude Desktop 的配置文件 'claude_desktop_config.json' 中提供 'uv' 的绝对路径。

基本使用方法

服务器成功运行后，您可以使用任何 MCP 客户端连接到该服务器。连接后，您可以使用以下资源和工具与Gmail进行交互：

可用资源:

'gmail://messages/{message_id}': 获取指定ID的邮件内容。
'gmail://threads/{thread_id}': 获取指定ID的邮件线程内容。

可用工具:

'compose_email': 撰写邮件草稿。
'send_email': 发送邮件。
'search_emails': 根据条件搜索邮件。
'query_emails': 使用Gmail查询语法搜索邮件。
'list_available_labels': 获取所有可用的Gmail标签。
'mark_message_read': 标记邮件为已读。
'add_label_to_message': 为邮件添加标签。
'remove_label_from_message': 从邮件移除标签。
'get_emails': 批量获取多封邮件的内容。

您可以通过 MCP 客户端提供的界面或指令来调用这些资源和工具，以实现与Gmail邮箱的交互。

关键词