项目简介

MCP Headless Gmail Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务器，专门为 LLM 应用提供 Gmail 功能。它允许 LLM 客户端通过标准化的 MCP 协议，远程安全地访问和操作 Gmail 邮箱，而无需在本地配置 Gmail 凭据或令牌。该服务器以 Docker 镜像形式提供，易于部署和使用。

主要功能点

获取最新邮件：获取 Gmail 收件箱中最新的邮件，可设置最大返回数量和是否只获取未读邮件，返回邮件元数据和部分邮件正文（前1000字符）。
获取完整邮件内容：对于超过 1000 字符的邮件，可以通过邮件 ID 或线程 ID 以及偏移量分块获取完整邮件正文。
发送邮件：通过 Gmail 发送邮件，支持纯文本和 HTML 格式邮件内容。
令牌刷新：提供独立的工具用于刷新 Google API 访问令牌，简化认证管理。
自动令牌刷新：服务器端自动处理访问令牌过期，无需手动干预。
Docker 部署：以 Docker 镜像形式发布，方便快捷部署，环境隔离性好。
无头运行：完全支持在无头环境中运行，无需浏览器或本地文件访问。
跨平台镜像：提供多平台 Docker 镜像，支持 linux/amd64, linux/arm64, linux/arm/v7 架构。

安装步骤

克隆仓库

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

安装 Python 依赖

确保已安装 Python 3.10 或更高版本。
```
pip install -e .
```

构建 Docker 镜像 (可选，推荐)

docker build -t mcp-headless-gmail .

服务器配置

对于 MCP 客户端（如 Claude Desktop），您需要配置 'mcpServers' 来连接到 MCP Headless Gmail Server。以下是使用 Docker 镜像部署的服务器配置示例：

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "buryhuang/mcp-headless-gmail:latest"
      ]
    }
  }
}

配置参数说明:

'"gmail"': 自定义的服务器名称，在客户端中用于引用该服务器。
'"command": "docker"': 指定启动服务器的命令为 'docker'。
'"args"': 启动 'docker' 命令的参数列表，用于运行 MCP Headless Gmail Server 的 Docker 镜像。
- '"run"': Docker 运行命令。
- '"-i"': 保持标准输入 (STDIN) 打开，即使没有连接到终端。
- '"--rm"': 容器退出后自动删除容器。
- '"buryhuang/mcp-headless-gmail:latest"': 要运行的 Docker 镜像名称和标签。

注意: Gmail API 凭据（如访问令牌、刷新令牌、客户端 ID 和客户端密钥） 不需要 作为环境变量传递给 Docker 容器。为了安全性和架构解耦，这些凭据应该在 MCP 客户端调用工具时作为工具参数传递。

基本使用方法

启动服务器

如果使用本地 Python 环境运行，执行以下命令：
```
mcp-server-headless-gmail
```
如果使用 Docker 镜像，服务器将在客户端通过 Docker 命令启动时自动运行。

使用 MCP 客户端调用工具

MCP Headless Gmail Server 提供以下工具，可以通过 MCP 客户端调用：

'gmail_refresh_token': 刷新访问令牌。首次使用或令牌过期时调用。需要提供 'google_refresh_token', 'google_client_id', 'google_client_secret'，以及可选的 'google_access_token' (如果已过期)。

{
  "tool_call": {
    "server_name": "gmail",
    "tool_name": "gmail_refresh_token",
    "arguments": {
      "google_refresh_token": "YOUR_REFRESH_TOKEN",
      "google_client_id": "YOUR_CLIENT_ID",
      "google_client_secret": "YOUR_CLIENT_SECRET"
      // "google_access_token": "YOUR_ACCESS_TOKEN" // 可选，如果已有过期 access token
    }
  }
}

'gmail_get_recent_emails': 获取最新邮件。需要提供 'google_access_token'，可选参数 'max_results' (最大邮件数，默认 10) 和 'unread_only' (是否只获取未读邮件，默认 false)。

{
  "tool_call": {
    "server_name": "gmail",
    "tool_name": "gmail_get_recent_emails",
    "arguments": {
      "google_access_token": "YOUR_ACCESS_TOKEN",
      "max_results": 5,
      "unread_only": true
    }
  }
}

'gmail_get_email_body_chunk': 获取邮件正文片段。需要提供 'google_access_token'，以及 'message_id' 或 'thread_id' 之一来指定邮件，可选参数 'offset' (偏移量，默认 0)。

{
  "tool_call": {
    "server_name": "gmail",
    "tool_name": "gmail_get_email_body_chunk",
    "arguments": {
      "google_access_token": "YOUR_ACCESS_TOKEN",
      "message_id": "MESSAGE_ID",
      "offset": 1000
    }
  }
}

'gmail_send_email': 发送邮件。需要提供 'google_access_token', 'to' (收件人), 'subject' (主题), 'body' (正文)，可选参数 'html_body' (HTML 格式正文)。

{
  "tool_call": {
    "server_name": "gmail",
    "tool_name": "gmail_send_email",
    "arguments": {
      "google_access_token": "YOUR_ACCESS_TOKEN",
      "to": "[email protected]",
      "subject": "Test Email from MCP",
      "body": "This is a test email.",
      "html_body": "<p>This is a <b>test</b> email.</p>"
    }
  }
}

获取 Google API 凭据

请参考仓库 README 文档 "Obtaining Google API Credentials" 章节，在 Google Cloud Console 中创建项目、启用 Gmail API、配置 OAuth 同意屏幕、创建 OAuth 客户端 ID 凭据，并获取 'client_id', 'client_secret', 'access_token', 'refresh_token'。确保在 OAuth 2.0 流程中授权以下 scope：
- 'https://www.googleapis.com/auth/gmail.readonly' (用于读取邮件)
- 'https://www.googleapis.com/auth/gmail.send' (用于发送邮件)
将获取到的 'client_id', 'client_secret', 'refresh_token' 安全地保存，并在调用 'gmail_refresh_token' 工具时提供。'access_token' 由 'gmail_refresh_token' 工具返回，并在后续调用其他 Gmail 工具时使用。

注意事项

安全性: 请妥善保管您的 Google API 凭据，避免泄露。
Docker 镜像: 推荐使用 Docker 镜像部署，简化安装和配置。
凭据管理: MCP Headless Gmail Server 强调凭据与服务器实现分离，凭据不存储在服务器端，而是在客户端调用工具时传递，提高了安全性。

关键词