Skip to main content
Glama
deenjakoruzh
iXanadu

gmail-mcp

by iXanadu
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

gmail-mcp

适用于 MCP 客户端的 Gmail 连接器。一个服务器，通过 OAuth 刷新令牌管理多个 Gmail 账户。发送真正的 MIME（文件路径附件、实时签名、发送后证明）。读取和组织邮件，而不会将数兆字节的 base64 倾倒给模型。

并非 Google 托管 Gmail MCP 的包装器 —— 它在主机上构建 RFC822，并直接与 gmail.googleapis.com 通信。

功能特性

  • 多账户 OAuth — 通过 accounts_add 添加邮箱；令牌存储在本地（权限 0600）

  • 发送 / 回复 / 转发 — 服务器构建 MIME，仅提供发件箱文件路径，上限 25 MB，幂等键，成功时返回证明

  • 读取 / 整理 — 搜索（会话 + 分页）、获取会话/邮件、标签、归档/删除、草稿

  • 附件 — 从 ~/Outbox 发送（可配置）；下载到 ~/Inbox（可配置）

  • 双传输 — stdio 用于本地测试工具；Streamable HTTP 位于网关之后，用于远程客户端

Related MCP server: Gmail MCP Server

要求

  • Python 3.12+（开发环境通过 pyenv 使用 3.13）

  • Google Cloud 桌面端 OAuth 客户端（客户端 ID + 密钥）

  • macOS 用于附带的 LaunchAgent 脚本（HTTP 服务）；Linux 可用于手动运行

快速开始

git clone https://github.com/iXanadu/gmcp.git
cd gmcp

# Python 3.12+ (example with pyenv)
pyenv virtualenv 3.13 gmail-mcp-3.13
pyenv local gmail-mcp-3.13
pip install -e '.[dev]'

# Config (see examples/)
cp examples/.env.example .env
cp examples/.keys.example .keys
chmod 600 .keys

# Sanity check
gmail-doctor

在运行 HTTP 传输之前，用你的 Google OAuth 凭据和 HTTP bearer 令牌填写 .keys。

Google Cloud Console（一次性设置）

你需要一个桌面端 OAuth 客户端 —— 不是服务账户，也不是全域委派。

步骤

位置

操作

1

API 和服务 → 库

启用 Gmail API

2

OAuth 同意屏幕

个人使用选择外部即可。在应用处于测试模式时，将你的 Google 账户添加为测试用户。

3

凭据 → 创建

OAuth 客户端 ID → 桌面应用

4

客户端设置

添加重定向 URI http://127.0.0.1:8767/oauth/callback（必须与 .env 中的 GMAIL_MCP_OAUTH_REDIRECT_URI 匹配）

5

.keys

将客户端 ID 和客户端密钥粘贴为 GMAIL_MCP_GOOGLE_CLIENT_ID / GMAIL_MCP_GOOGLE_CLIENT_SECRET

首次调用 accounts_add 时，Google 会请求同意授权。作用域在服务器中是固定的：读取/发送/整理邮件，外加读取发件身份签名（不缓存）。

无需在聊天中提供用户名/密码、应用专用密码或粘贴的刷新令牌。

连接邮箱（accounts_add）

accounts_add 会打开浏览器以完成 Google 同意授权。它只在 stdio 传输（gmail-mcp）上运行，不能通过 HTTP 运行。

gmail-mcp   # stdio — required for accounts_add and accounts_remove

从你的 MCP 客户端调用 accounts_add。同意授权完成后，服务器会记录 Google 返回的 Gmail 地址；该地址就是所有其他工具的 account 键。

令牌会存放到 ~/.config/gmail-mcp/tokens/（权限 0600）。如有需要，可将该目录复制到运行同一服务器的任何其他主机。

无头服务器（无本地浏览器）

OAuth 回调地址是 http://127.0.0.1:8767/oauth/callback。没有显示器的机器仍然需要在某处有一个浏览器来打开 Google 登录页面。两种常见模式：

A — SSH 端口转发（在笔记本电脑上完成同意授权）

在无头主机上启动 stdio MCP / accounts_add。然后在你的笔记本电脑上：

ssh -L 8767:127.0.0.1:8767 user@headless-host

打开服务器打印的授权 URL（或在隧道建立后通过你的 MCP 客户端触发 accounts_add）。回调会通过隧道到达无头主机上的 127.0.0.1:8767。

B — 在桌面端完成同意授权，然后复制令牌

在配有浏览器且使用相同 .env / .keys 的 Mac 或 PC 上运行一次 accounts_add。同意授权后，将 ~/.config/gmail-mcp/tokens/ 复制到生产主机（路径相同，权限 0600）。除非 Google 撤销刷新令牌，否则无需再次授权。

部署架构

典型的生产环境拆分：

┌─────────────────────┐         ┌──────────────────────────┐
│  Operator machine   │         │  MCP server (Linux/macOS) │
│  (browser for OAuth)│         │  gmail-mcp-http           │
│  accounts_add       │  copy   │  127.0.0.1:8879           │
│  token files ───────┼────────►│  + .env / .keys           │
└─────────────────────┘  tokens └───────────┬──────────────┘
                                            │
                              Cloudflare / gateway / TLS
                                            │
                                    Hand / remote MCP client

  • 不要为 MCP HTTP 将操作员的笔记本电脑暴露到公共互联网。HTTP 在服务器上绑定回环地址（127.0.0.1:8879）；反向代理终止 TLS 并将流量转发到该端口。

  • OAuth 在存在浏览器的地方完成（操作员机器或 SSH 隧道）。令牌 JSON 文件会被复制到服务器。

  • 网关指向你控制的服务器主机名（例如 mcp.example.com），而不是 OAuth 工作站。

  • 生成一个长的随机 GMAIL_MCP_HTTP_BEARER_TOKEN；网关以 Authorization: Bearer … 的形式提供它。

部署后：运行 gmail-doctor、./scripts/start.sh（macOS LaunchAgent）或你自己的 systemd 单元，然后通过 HTTP 调用 accounts_list 确认令牌。

配置

非敏感设置位于 .env；机密信息位于 .keys（填充内容后切勿提交任一文件）。参见 examples/.env.example 和 examples/.keys.example。

Variable

File

Purpose

GMAIL_MCP_ENVIRONMENT

.env

用于日志/状态的标签

GMAIL_MCP_LOG_LEVEL

.env

服务器日志级别

GMAIL_MCP_HTTP_HOST

.env

HTTP 绑定地址（默认 127.0.0.1）

GMAIL_MCP_HTTP_PORT

.env

HTTP 端口（默认 8879）

GMAIL_MCP_OUTBOX_ROOT

.env

发送附件路径的根目录

GMAIL_MCP_DOWNLOAD_ROOT

.env

get_attachment 写入的根目录

GMAIL_MCP_TOKENS_DIR

.env

OAuth 令牌存储目录

GMAIL_MCP_OAUTH_REDIRECT_URI

.env

OAuth 回环回调

GMAIL_MCP_GOOGLE_CLIENT_ID

.keys

Google OAuth 客户端 ID

GMAIL_MCP_GOOGLE_CLIENT_SECRET

.keys

Google OAuth 客户端密钥

GMAIL_MCP_HTTP_BEARER_TOKEN

.keys

HTTP 传输的 Bearer 令牌

更改配置后运行 gmail-doctor。

传输方式

stdio（本地）

gmail-mcp

注册所有工具，包括 accounts_add 和 accounts_remove。

使用 venv 中的 gmail-mcp 二进制文件，并将 cwd 设置为仓库目录（以便加载 .env / .keys），接入 Cursor / Claude Code 的 MCP 配置。

Streamable HTTP（网关）

gmail-mcp-http

默认绑定 127.0.0.1:8879。要求提供 Authorization: Bearer <GMAIL_MCP_HTTP_BEARER_TOKEN>；没有有效令牌的请求将收到 401 响应。

手动允许列表（仅 HTTP）：读取/整理工具，以及 send、reply、forward、draft_create、draft_send、accounts_list 和 gmail_status。账户管理仍保留在 stdio 上。

macOS 服务（用户 LaunchAgent）

./scripts/start.sh    # install plist → ~/Library/LaunchAgents, load
./scripts/stop.sh
./scripts/restart.sh

如果你的检出目录或 pyenv 名称不同，请编辑 launchd/com.gmail-mcp.plist 中的路径。日志输出到 logs/。

在 Linux 上，使用 systemd 以相同的回环绑定运行 gmail-mcp-http —— 参见上文部署架构。

工具

Tool

Notes

gmail_status

版本与配置摘要

accounts_list

已连接地址与令牌健康状态

accounts_add

OAuth 同意授权（仅 stdio）

accounts_remove

撤销并删除令牌（仅 stdio）

search

Gmail 查询；返回会话

get_thread / get_message

format=plain 或 full

get_attachment

写入下载根目录下

send / reply / forward

仅接受路径；拒绝 JSON 中的 content / base64

draft_create / draft_send

与发送相同的附件/证明规则

labels_list / labels_create

用户与系统标签

label / unlabel

逗号分隔的名称或 ID

archive / trash / untrash

会话级

除 accounts_list、accounts_add 和 gmail_status 外，每个工具都需要一个 account 参数（Gmail 地址）。

发送规则（摘要）

  • 附件：{ "path": "/absolute/or/under/outbox/file.pdf" } —— 不支持内联 base64

  • 发送时追加实时 Gmail 签名（不缓存）

  • 签名后可选 footer

  • 返回证明：大小、链接；ok 为 false → 工具报错（例如附件被截断或 google.com/url 重写）

测试

pytest tests/ -v

使用模拟的 Gmail HTTP；无需真实邮箱。

规格说明

产品需求：docs/specs/gmail-mcp-pec.md

许可证

Apache-2.0

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Gmail MCP Server

    brentwpeterson
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables interaction with Gmail through MCP-compatible clients to list, read, search, and send emails. It supports advanced features such as managing labels, handling threaded replies, and utilizing Gmail's native search syntax.
    49
    2
    MIT

  • Gmail MCP Server

    fred-drake
    A
    license
    A
    quality
    D
    maintenance
    Provides access to Gmail functionalities including listing unread emails, searching via query syntax, and managing messages through archiving or marking as read. It enables MCP clients to securely interact with and organize email data using the Gmail API.
    5
    MIT

  • Gmail MCP Server

    cristip73
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Gmail through the MCP protocol, supporting sending, reading, searching, replying, forwarding, managing drafts and labels, and saving attachments.
    15
    3
    MIT

  • gmail-mcp

    RonildoBraga
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables interacting with multiple Gmail accounts through a single MCP server, supporting search, labels, drafts, and thread management with per-account OAuth.

View all related MCP servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/iXanadu/pigeon-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server