MCP无头Gmail服务器（NPM和Docker）
](https://www.npmjs.com/package/@peakmojo/mcp-server-headless-gmail) ](https://hub.docker.com/r/buryhuang/mcp-headless-gmail) 
一种MCP（模型上下文协议）服务器，无需本地凭据或令牌设置即可提供get、send Gmail。
为什么选择MCP无头Gmail服务器？
关键优势
- 无头和远程操作：与其他需要在docker和本地文件访问之外运行的MCP Gmail解决方案不同，此服务器可以在无浏览器、无本地文件访问的远程环境中完全无头运行。
- 解耦架构：任何客户端都可以独立完成OAuth流，然后将凭据作为上下文传递给此MCP服务器，从而在凭据存储和服务器实现之间实现完全分离。
不错，但并不挑剔
- 专注功能：在许多用例中，特别是对于营销应用程序，只需要访问Gmail，而不需要像Calendar这样的额外谷歌服务，这使得这种专注的实现非常理想。
- Docker就绪：设计时考虑了容器化，以实现隔离良好、独立于环境、一键式设置。
- 可靠的依赖关系：基于维护良好的googleapi-python客户端库构建。
特性
- 从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镜像
# 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": "
This is a test email sent via MCP Gmail server
"
}令牌刷新工作流
- 首先，请致电
gmail_refresh_token工具具有以下任一功能：
- 您的完整凭据（访问令牌、刷新令牌、客户端ID和客户端密钥），或 - 如果访问令牌已过期，则只需刷新令牌、客户端ID和客户端密钥
- 将返回的新访问令牌用于后续API调用。
- 如果您收到指示令牌过期的响应，请调用
gmail_refresh_token再次使用工具获取新令牌。
这种方法简化了大多数API调用，不需要为每个操作提供客户端凭据，同时仍然在需要时启用令牌刷新。
获取Google API证书
要获得所需的Google API证书，请按照以下步骤操作：
- 转到 谷歌云控制台
- 创建新项目
- 启用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文件。
