MCP 服务器

MCP Headless Gmail Server

一个无头服务器，可以通过 API 调用读取和发送 Gmail 电子邮件，无需本地凭据或浏览器访问，专为在容器化环境中远程运行而设计。

README

MCP 无头 Gmail 服务器

一个 MCP (模型上下文协议) 服务器，提供获取、发送 Gmail 的功能，无需本地凭据或令牌设置。

为什么选择 MCP 无头 Gmail 服务器？

关键优势

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

锦上添花

专注的功能: 在许多用例中，特别是对于营销应用程序，只需要 Gmail 访问，而不需要像日历这样的其他 Google 服务，这使得这种专注的实现成为理想选择。
Docker 就绪: 专为容器化而设计，实现良好隔离、环境独立、一键式设置。
可靠的依赖项: 构建在维护良好的 google-api-python-client 库之上。

功能

从 Gmail 获取最新的电子邮件，包含邮件正文的前 1k 个字符
使用 offset 参数获取 1k 块的完整电子邮件正文内容
通过 Gmail 发送电子邮件
单独刷新访问令牌
自动刷新令牌处理

前提条件

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

安装

# 克隆存储库
git clone https://github.com/yourusername/mcp-headless-gmail.git
cd mcp-headless-gmail

# 安装依赖
pip install -e .

Docker

构建 Docker 镜像

# 构建 Docker 镜像
docker build -t mcp-headless-gmail .

与 Claude Desktop 一起使用

Docker 用法

您可以通过将以下内容添加到您的 Claude 配置中，来配置 Claude Desktop 以使用 Docker 镜像：

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

注意：使用此配置，您需要在工具调用中提供您的 Google API 凭据，如使用工具部分所示。 Gmail 凭据不会作为环境变量传递，以保持凭据存储和服务器实现之间的分离。

跨平台发布

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

创建一个新的构建器实例（如果尚未创建）：
```
docker buildx create --use
```

构建并推送适用于多个平台的镜像:

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

验证镜像是否可用于指定的平台:

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": "recipient@example.com",
  "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>"
}

令牌刷新工作流程

首先使用以下任一方式调用 gmail_refresh_token 工具：
- 您的完整凭据（访问令牌、刷新令牌、客户端 ID 和客户端密钥），或
- 如果访问令牌已过期，则仅使用您的刷新令牌、客户端 ID 和客户端密钥
将返回的新访问令牌用于后续 API 调用。
如果您收到指示令牌过期的响应，请再次调用 gmail_refresh_token 工具以获取新令牌。

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

获取 Google API 凭据

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

转到 Google Cloud Console
创建一个新项目
启用 Gmail API
配置 OAuth 同意屏幕
创建 OAuth 客户端 ID 凭据（选择“桌面应用”作为应用程序类型）
保存客户端 ID 和客户端密钥
使用 OAuth 2.0 获取具有以下范围的访问令牌和刷新令牌：
- https://www.googleapis.com/auth/gmail.readonly（用于读取电子邮件）
- https://www.googleapis.com/auth/gmail.send（用于发送电子邮件）