MCP无头Gmail
一个无头服务器，通过API调用启用读取和发送Gmail邮件的功能，无需本地凭据或浏览器访问，专为在远程容器化环境中运行而设计。
MCP 服务配置
复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用
{
"mcpServers": {
"gmail": {
"args": [
"@peakmojo/mcp-server-headless-gmail"
],
"command": "npx"
}
}
}服务介绍
MCP 无头 Gmail 服务器
一个 MCP（Model Context Protocol）服务器，提供无需本地凭证或令牌设置即可获取和发送 Gmail 的功能。
为什么选择 MCP 无头 Gmail 服务器？
关键优势
- 无头 & 远程操作：与需要在 Docker 外运行并访问本地文件的其他 MCP Gmail 解决方案不同，此服务器可以在没有浏览器和不访问本地文件的远程环境中完全无头运行。
- 解耦架构：任何客户端都可以独立完成 OAuth 流程，然后将凭证作为上下文传递给此 MCP 服务器，从而在凭证存储和服务实现之间创建了完全分离。
虽好但非关键
- 专注的功能：在许多用例中，特别是营销应用，只需要访问 Gmail 而不需要额外的 Google 服务（如日历），使得这种专注的实现非常理想。
- Docker 就绪：设计时考虑了容器化，以实现良好的隔离、环境无关性以及一键设置。
- 可靠的依赖项：基于维护良好的 google-api-python-client 库构建。
功能
- 获取 Gmail 中最新的邮件，并显示正文的前 1000 个字符
- 使用偏移参数分块获取完整邮件正文内容（每块 1000 个字符）
- 通过 Gmail 发送邮件
- 分别刷新访问令牌
- 自动处理刷新令牌
先决条件
- Python 3.10 或更高版本
- Google API 凭证（客户端 ID、客户端密钥、访问令牌和刷新令牌）
安装
# Clone the repository
git clone https://github.com/yourusername/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 一起使用
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"
}
这将返回一个新的访问令牌及其过期时间，你可以用它来进行后续调用。
获取最近的邮件
检索每封邮件正文的前1000个字符的最近邮件：
{
"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）
获取完整的邮件正文内容
对于正文超过1000个字符的邮件，您可以分块获取完整内容：
{
"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（用于发送邮件）
令牌刷新
这台服务器实现了自动刷新令牌功能。当您的访问令牌过期时，Google API 客户端将使用刷新令牌、客户端 ID 和客户端密钥来获取新的访问令牌，而无需用户干预。
安全提示
此服务器需要直接访问您的 Google API 凭据。请始终确保您的令牌和凭据安全，并且不要与不可信的第三方共享。
许可证
详情请参阅 LICENSE 文件。
