MCP Headless Gmail Server

MCP Headless Gmail Server（NPM 和 Docker）

一个 MCP（Model Context Protocol）服务，无需在本地设置凭据或令牌，即可获取和发送 Gmail 邮件。

为什么选择 MCP Headless Gmail Server？

关键优势

• 无头和远程运行：与其他需要在 Docker 外运行并访问本地文件的 MCP Gmail 方案不同，此服务可在远程环境中完全无头运行，无需浏览器，也无需访问本地文件。
• 解耦架构：任何客户端都可以独立完成 OAuth 流程，然后将凭据作为上下文传递给此 MCP 服务，实现凭据存储与服务实现的完全分离。

优点，但并非关键

• 专注于核心功能：在许多使用场景中，尤其是营销应用，只需访问 Gmail，无需使用 Calendar 等其他 Google 服务，因此这种专注的实现十分理想。
• 支持 Docker：专为容器化设计，提供隔离良好、不受环境影响的一键式设置。
• 可靠的依赖项：基于维护良好的 google-api-python-client 库构建。

功能

• 获取 Gmail 中最新的邮件，并返回正文的前 1k 个字符
• 使用 offset 参数，以 1k 字符为单位获取完整邮件正文
• 通过 Gmail 发送邮件
• 单独刷新访问令牌
• 自动处理刷新令牌

前置条件

• Python 3.10 或更高版本
• Google API 凭据（客户端 ID、客户端密钥、访问令牌和刷新令牌）

安装

# Clone the repository
git clone https://github.com/baryhuang/mcp-headless-gmail.git
cd mcp-headless-gmail

# Install dependencies
pip install -e .

Docker

构建 Docker 镜像

# Build the Docker image
docker build -t mcp-headless-gmail .

在 Claude Desktop 中使用

你可以将以下内容添加到 Claude 配置中，配置 Claude Desktop 使用 Docker 镜像：

docker

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

npm version

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@peakmojo/mcp-server-headless-gmail"
      ]
    }
  }
}

注意：使用此配置时，你需要按照使用工具一节中的说明，在工具调用中提供 Google API 凭据。为保持凭据存储与服务实现相互分离，不会将 Gmail 凭据作为环境变量传递。

跨平台发布

如需为多个平台发布 Docker 镜像，可以使用 docker buildx 命令。请按以下步骤操作：

1. 创建新的构建器实例（如果尚未创建）：

   docker buildx create --use
   

2. 为多个平台构建并推送镜像：

   docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .
   

3. 确认镜像可用于指定的平台：

   docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest
   

使用方法

此服务通过 MCP 工具提供 Gmail 功能。借助专用的令牌刷新工具，身份验证处理更加简单。

启动服务

mcp-server-headless-gmail

使用工具

使用 Claude 等 MCP 客户端时，有两种主要的身份验证处理方式：

刷新令牌（首次使用或令牌过期时）

如果你同时拥有访问令牌和刷新令牌：

{
  "google_access_token": "your_access_token",
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

如果访问令牌已过期，你可以只使用刷新令牌进行刷新：

{
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

这将返回新的访问令牌及其过期时间，可用于后续调用。

获取最近的邮件

获取最近的邮件，并返回每封邮件正文的前 1k 个字符：

{
  "google_access_token": "your_access_token",
  "max_results": 5,
  "unread_only": false
}

响应包含：

• 邮件元数据（id、threadId、from、to、subject、date 等）
• 邮件正文的前 1000 个字符
• body_size_bytes：邮件正文的总字节数
• contains_full_body：布尔值，表示是否包含完整正文（true）或内容已截断（false）

获取完整邮件正文内容

对于正文超过 1k 个字符的邮件，可以分块获取完整内容：

{
  "google_access_token": "your_access_token",
  "message_id": "message_id_from_get_recent_emails",
  "offset": 0
}

也可以通过会话 ID 获取邮件内容：

{
  "google_access_token": "your_access_token",
  "thread_id": "thread_id_from_get_recent_emails",
  "offset": 1000
}

响应包含：

• 从指定偏移量开始的 1k 邮件正文分块
• body_size_bytes：邮件正文的总大小
• chunk_size：返回分块的大小
• contains_full_body：布尔值，表示分块是否包含正文的剩余部分

要获取较长邮件的完整正文，请按顺序多次调用，每次将偏移量增加 1000，直到 contains_full_body 为 true。

发送邮件

{
  "google_access_token": "your_access_token",
  "to": "[email protected]",
  "subject": "Hello from MCP Gmail",
  "body": "This is a test email sent via MCP Gmail server",
  "html_body": "<p>This is a <strong>test email</strong> sent via MCP Gmail server</p>"
}

令牌刷新工作流

1. 首先调用 gmail_refresh_token 工具，提供以下任一凭据：
   • 完整凭据（访问令牌、刷新令牌、客户端 ID 和客户端密钥），或
   • 如果访问令牌已过期，仅提供刷新令牌、客户端 ID 和客户端密钥
2. 后续 API 调用使用返回的新访问令牌。
3. 如果收到令牌过期的响应，再次调用 gmail_refresh_token 工具以获取新令牌。

这种方式简化了大多数 API 调用，无需每次操作都提供客户端凭据，同时仍可在需要时刷新令牌。

获取 Google API 凭据

要获取所需的 Google API 凭据，请按以下步骤操作：

1. 前往 Google Cloud Console
2. 创建新项目
3. 启用 Gmail API
4. 配置 OAuth 同意屏幕
5. 创建 OAuth 客户端 ID 凭据（将应用类型选为 "Desktop app"）
6. 保存客户端 ID 和客户端密钥
7. 使用 OAuth 2.0 获取访问令牌和刷新令牌，并申请以下范围：
   • https://www.googleapis.com/auth/gmail.readonly（用于读取邮件）
   • https://www.googleapis.com/auth/gmail.send（用于发送邮件）

令牌刷新

此服务支持自动刷新令牌。访问令牌过期时，Google API 客户端会使用刷新令牌、客户端 ID 和客户端密钥获取新的访问令牌，无需用户干预。

安全说明

此服务需要直接访问你的 Google API 凭据。请始终妥善保管令牌和凭据，切勿与不可信的对象共享。

许可证

详情请参阅 LICENSE 文件。