AI导哈

Gmail MCP 服务器

一个为Claude提供Gmail访问权限的MCP（Model Context Protocol）服务器，具备完整的OAuth 2.1授权服务器功能，支持动态客户端注册。

  • by jsflax
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 jsflax/gmail-mcp

使用说明

Gmail MCP服务器

MCP（模型上下文协议）服务器，为Claude提供访问您的Gmail的权限，具有完整的OAuth 2.1授权服务器和动态客户端注册功能。

特性

  • 完整的OAuth 2.1授权服务器（RFC 8414、RFC 7591、RFC 9728）
  • 动态客户端注册-Claude Code自动注册
  • PKCE支持（RFC 7636）
  • Claude Code中的第一类“身份验证”按钮 /mcp 菜单
  • Gmail工具：列表、阅读、搜索、发送、回复、草稿、存档、垃圾箱、标签、附件

先决条件

需要Node.js 18+。通过安装 nodejs.org 或者：

brew install node

设置

  1. 克隆和安装依赖关系：

    git clone <repo-url> gmail-mcp
cd gmail-mcp
npm install

  2. 构建：

    npm run build

  3. 启动服务器：

    npm start

    服务器运行在 http://localhost:3100 默认情况下。覆盖 PORT=3200 npm start.

  4. 配置Claude代码 (~/.mcp.json):

    {
  "mcpServers": {
    "gmail": {
      "type": "sse",
      "url": "http://localhost:3100/sse"
    }
  }
}

  5. 通过克劳德代码进行身份验证：

    • 跑 /mcp 克劳德代码
    • 在gmail服务器上单击“身份验证”
    • 在浏览器中完成Google OAuth

    注： 谷歌将显示“此应用程序未经验证”警告屏幕。对于没有经过谷歌验证流程的应用程序来说，这是正常的。要继续，请执行以下操作：

    1. 点击 高级
    2. 点击 转到gmail mcp（不安全）
    3. 查看请求的权限（读取和修改Gmail），然后单击 允许

    您的凭据存储在本地计算机上，永远不会发送到任何第三方服务器。

配置

内置Google OAuth凭据，无需设置。首次使用时，系统会提示您通过谷歌的同意屏幕授权您的Gmail。

用户特定的配置文件存储在 ~/.config/gmail-mcp/:

文件 描述
credentials.json 可选的 --使用您自己的内置Google OAuth凭据覆盖内置的Google OAuth凭据
token.json 您的Google OAuth令牌（授权后自动生成）
clients.json 注册的MCP客户端（自动生成）
access_tokens.json 已发放的访问令牌（自动生成）

登录时自动启动（macOS）

运行安装脚本以设置LaunchAgent：

./scripts/install.sh

这将：

  • 检测您的节点安装
  • 生成具有正确路径的plist
  • 安装到 ~/Library/LaunchAgents/
  • 立即启动服务器

要卸载，请执行以下操作：

./scripts/uninstall.sh

日志被写入 ~/.config/gmail-mcp/stdout.log 和 stderr.log.

可用工具

工具 说明
list_emails 使用可选过滤器列出收件箱中的电子邮件
read_email 按ID阅读完整的电子邮件内容
search_emails 使用Gmail查询语法进行搜索
send_email 撰写并发送一封新电子邮件
reply_to_email 回复现有电子邮件
draft_email 创建草稿而不发送
mark_as_read 将电子邮件标记为已读
mark_as_unread 将电子邮件标记为未读
archive_email 存档电子邮件（从收件箱中删除）
trash_email 将电子邮件移至垃圾箱
add_label 在电子邮件中添加标签
remove_label 从电子邮件中删除标签
list_labels 列出所有Gmail标签
get_thread 获取对话中的所有电子邮件
get_attachment 下载电子邮件附件

Gmail搜索语法

这 search_emails 和 list_emails 工具支持Gmail的查询语法：

  • is:unread -未读电子邮件
  • from:someone@example.com -来自特定发件人
  • subject:invoice -主题包含“发票”
  • has:attachment -有附件
  • after:2025/01/01 -约会之后
  • before:2025/12/31 -日期之前
  • label:important -具有特定标签

建筑

┌─────────────────┐      ┌──────────────────────────────────────┐
│   Claude Code   │◄────►│         Gmail MCP Server             │
│                 │ SSE  │                                      │
│  /mcp menu      │      │  ┌─────────────────────────────────┐ │
│  shows          │      │  │ OAuth 2.1 Authorization Server  │ │
│  "Authenticate" │      │  │  - Dynamic client registration  │ │
│                 │      │  │  - PKCE support                 │ │
└─────────────────┘      │  │  - Token management             │ │
                         │  └──────────────┬──────────────────┘ │
                         │                 │                    │
                         │  ┌──────────────▼──────────────────┐ │
                         │  │      Google OAuth Proxy         │ │
                         │  │  - Redirects to Google          │ │
                         │  │  - Stores Google tokens         │ │
                         │  └──────────────┬──────────────────┘ │
                         │                 │                    │
                         │  ┌──────────────▼──────────────────┐ │
                         │  │        Gmail API Tools          │ │
                         │  │  - list, read, search, etc.     │ │
                         │  └─────────────────────────────────┘ │
                         └──────────────────────────────────────┘

发展

npm run build   # Compile TypeScript
npm start       # Run server
npm run auth    # Standalone Google OAuth (alternative to browser flow)

端点

端点 描述
GET /health 健康检查和状态
GET /.well-known/oauth-protected-resource RFC 9728元数据
GET /.well-known/oauth-authorization-server RFC 8414元数据
POST /oauth/register 动态客户端注册
GET /oauth/authorize 授权端点
POST /oauth/token 令牌端点
GET /sse MCP SSE端点（受保护）

相关 MCP