STARWARCLOUD STARWAR.AI
返回市场
无头gmail服务器

无头gmail服务器

作者：baryhuang54 星标更新：2025-05-25
安装使用来源：spider==github.com

项目介绍

MCP 无头Gmail服务器（NPM & Docker）

npm 版本 Docker 拉取次数 许可证: MIT

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

<a href="https://glama.ai/mcp/servers/@baryhuang/mcp-headless-gmail"> <img width="380" height="200" src="https://gips3.baidu.com/it/u=959723254,397133773&fm=3081&app=3081&f=PNG?w=760&h=400" alt="无头Gmail服务器 MCP服务器" /> </a>

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

关键优势

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

好处但非关键

  • 专注的功能性：在许多用例中，特别是营销应用，只需要访问Gmail而不需要额外的Google服务如日历，使得这种专注的实现非常理想。
  • Docker就绪：考虑到容器化设计，以实现环境无关的一键安装。
  • 可靠的依赖项：基于维护良好的google-api-python-client库构建。

功能

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

预备条件

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

安装

# 克隆仓库
git clone https://github.com/baryhuang/mcp-headless-gmail.git
cd mcp-headless-gmail

# 安装依赖项
pip install -e .

Docker

构建Docker镜像

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

使用Claude Desktop

你可以配置Claude Desktop使用Docker镜像，通过在你的Claude配置中添加以下内容：

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命令。按照以下步骤操作：

  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：布尔值表示该块是否包含剩余的正文

为了获取长邮件的完整正文，可以通过增加每次调用的偏移量直到contains_full_body变为true来连续调用。

发送邮件

{
  "google_access_token": "your_access_token",
  "to": "recipient@example.com",
  "subject": "来自MCP Gmail的问候",
  "body": "这是通过MCP Gmail服务器发送的测试邮件",
  "html_body": "<p>这是通过MCP Gmail服务器发送的<strong>测试邮件</strong></p>"
}

令牌刷新工作流

  1. 首先调用gmail_refresh_token工具，传递：
    • 你的全部凭证（访问令牌、刷新令牌、客户端ID和客户端密钥），或者
    • 如果访问令牌已过期，则只需传递刷新令牌、客户端ID和客户端密钥
  2. 使用返回的新访问令牌进行后续API调用。
  3. 如果收到令牌过期的响应，再次调用gmail_refresh_token工具以获取新令牌。

这种方法简化了大多数API调用，无需为每个操作都提供客户端凭证，同时在需要时仍能刷新令牌。

获取Google API凭证

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

  1. 访问Google Cloud控制台
  2. 创建一个新的项目
  3. 启用Gmail API
  4. 配置OAuth同意屏幕
  5. 创建OAuth客户端ID凭证（选择“桌面应用”作为应用程序类型）
  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文件。