AI导哈

无头Gmail服务器

一个无需本地凭证或令牌设置即可获取和发送Gmail的MCP服务器，适用于远程无浏览器环境。

  • by baryhuang
  • Python
  • 本地部署
  • 55 星标
  • 更新于
在 GitHub 查看 baryhuang/mcp-headless-gmail

使用说明

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

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

  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、发件人、收件人、主题、日期等）
  • 电子邮件正文的前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>"
}

令牌刷新工作流

  1. 首先，请致电 gmail_refresh_token 工具具有以下任一功能：
    • 您的完整凭据（访问令牌、刷新令牌、客户端ID和客户端密钥），或
    • 如果访问令牌已过期，则只需刷新令牌、客户端ID和客户端密钥
  2. 将返回的新访问令牌用于后续API调用。
  3. 如果您收到指示令牌过期的响应，请调用 gmail_refresh_token 再次使用工具获取新令牌。

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

获取Google API证书

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

  1. 转到 谷歌云控制台
  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文件。

相关 MCP