MCP 无头 Gmail 服务器

npm 版本 Docker拉取许可证：MIT

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

为什么选择 MCP Headless Gmail 服务器？

关键优势

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

不错，但不是批评

重点功能：在许多用例中，特别是对于营销应用程序，只需要访问 Gmail，而无需日历等额外的 Google 服务，这使得这种重点实现成为理想选择。
Docker-Ready ：设计时考虑了容器化，可实现良好隔离、独立于环境的一键式设置。
可靠的依赖关系：建立在维护良好的 google-api-python-client 库上。

Related MCP server: Systemprompt MCP Gmail Server

特征

获取 Gmail 最新电子邮件正文的前 1k 个字符
使用偏移参数以 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 镜像：

码头工人

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

npm 版本

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

注意：使用此配置，您需要在工具调用中提供您的 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、发件人、收件人、主题、日期等）
电子邮件正文的前 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为真。

发送电子邮件

{
  "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 （用于发送电子邮件）

令牌刷新

此服务器实现了令牌自动刷新功能。当您的访问令牌过期时，Google API 客户端将使用刷新令牌、客户端 ID 和客户端密钥来获取新的访问令牌，无需用户干预。

安全说明

此服务器需要直接访问您的 Google API 凭据。请始终确保您的令牌和凭据安全无虞，切勿与不受信任的第三方共享。

执照

有关详细信息，请参阅 LICENSE 文件。

MCP Headless Gmail Server