AI导哈

Gmail MCP服务器

一个基于Model Context Protocol（MCP）的服务器，通过OAuth2认证使AI助手能够与Gmail交互，具有安全优先的设计。

  • by JaviEzpeleta
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 javiezpeleta/gmail-mcp-server

使用说明

📧 Gmail MCP服务器

强大的MCP（模型上下文协议）服务器，使AI助手能够 通过OAuth2身份验证与Gmail交互 安全第一设计. 使用TypeScript构建，旨在与Claude Desktop无缝集成 以及其他MCP兼容客户端。

📑 目录

✨ 特性

  • 🛡️ 安全第一 -默认情况下，仅草稿模式可防止意外发送电子邮件
  • 📝 智能草稿 -为新电子邮件创建草稿，并使用自定义内容进行回复
  • 📬 列出电子邮件 -使用高级过滤选项检索最近的电子邮件
  • 📖 获取电子邮件详细信息 -获取完整的电子邮件内容，包括附件信息
  • 🔍 搜索电子邮件 -使用Gmail强大的搜索语法查找特定电子邮件
  • ✉️ 发送电子邮件 -直接发送（默认禁用，谨慎启用）
  • 🔐 安全OAuth2 -支持刷新令牌的行业标准身份验证
  • 🎯 类型安全 -具有严格类型的完整TypeScript实现
  • 🚀 高性能 -通过并行处理和智能缓存进行优化

📋 先决条件

在开始之前，请确保您已经：

  • Node.js 18.0或更高
  • npm 或 纱线 包管理器
  • Google账户 启用Gmail
  • 谷歌云控制台 访问
  • 克劳德桌面 （可选，用于集成）

📦 安装

  1. 克隆存储库：
git clone https://github.com/JaviEzpeleta/gmail-mcp-server.git
cd gmail-mcp-server
  1. 安装依赖项：
npm install
  1. 创建环境文件：
cp .env.example .env

🛡️ 安全说明：默认情况下，为了安全起见，禁用直接电子邮件发送。服务器将创建草稿，您可以从Gmail手动查看和发送。

⚙️ 配置

1.谷歌云控制台设置

  1. 创建或选择项目：

    • 首选 谷歌云控制台
    • 点击项目下拉菜单，选择“新建项目”
    • 为您的项目命名（例如，“Gmail MCP服务器”）
    • 点击“创建”

  2. 启用Gmail API：

    • 在侧边栏中，导航到 API和服务 → 图书馆
    • 搜索“Gmail API”
    • 点击 Gmail API 从结果来看
    • 点击 启用
    • 等待API启用（通常需要几秒钟）

2.创建OAuth2凭据

  1. 配置OAuth同意屏幕：

    • 首选 API和服务 → OAuth同意屏幕
    • 选择“外部”用户类型（除非您有Google Workspace帐户）
    • 填写必填字段：
      • 应用程序名称：“Gmail MCP服务器”
      • 用户支持电子邮件：您的电子邮件
      • 开发者联系人：您的电子邮件
    • 添加作用域：
      • https://www.googleapis.com/auth/gmail.readonly
      • https://www.googleapis.com/auth/gmail.send
      • https://www.googleapis.com/auth/gmail.modify
    • 添加测试用户（重要！）：
      • 添加您的Gmail地址和您要使用的任何其他帐户
    • 保存并继续执行所有步骤

  2. 创建OAuth客户端：

    • 首选 API和服务 → 凭证
    • 点击 +创建凭据 → OAuth客户端ID
    • 应用程序类型： Web应用程序 ⚠️ （非桌面应用程序）
    • 名称：“Gmail MCP Web客户端”
    • 配置授权重定向URI：
      • 点击 +添加URI
      • 添加： http://localhost:8765/oauth2callback （默认端口）
      • 如果您计划使用自定义端口，请添加： http://localhost:YOUR_PORT/oauth2callback
    • 点击 创建
    • 下载凭据 （您将看到一个下载按钮或JSON选项）
    • 保存 client_id 和 client_secret 从下载的文件

⚠️ 重要：桌面应用程序类型不允许自定义重定向URI，但我们需要 localhost:PORT/oauth2callback 为了使OAuth流程正常工作。这就是我们使用 Web应用程序 相反。

3.生成刷新令牌

  1. 将凭据添加到.env：
GMAIL_CLIENT_ID=your_client_id_here
GMAIL_CLIENT_SECRET=your_client_secret_here
GMAIL_REFRESH_TOKEN=
# Security: Keep this false unless you need direct sending
GMAIL_ALLOW_DIRECT_SEND=false
# OAuth setup port (must match the redirect URI you configured above)
OAUTH_REDIRECT_PORT=8765

💡 端口配置：The OAUTH_REDIRECT_PORT 必须与您在Google Cloud Console重定向URI中配置的端口匹配。如果您使用 http://localhost:8765/oauth2callback请将其保持为8765。如果使用了其他端口，请相应地更新此值。

  1. 运行安装脚本：
npm run setup
# or
npm run dev src/get-refresh-token-desktop.ts

  1. 授权申请：

    • 浏览器窗口将自动打开
    • 使用您的Google帐户登录
    • 授予所有请求的权限
    • 您将被重定向到成功页面

  2. 保存刷新令牌：

    • 终端将显示您的刷新令牌
    • 复制完整 GMAIL_REFRESH_TOKEN 价值
    • 将其添加到您的 .env 文件

🚀 用法

独立服务器

  1. 构建项目：
npm run build
  1. 启动服务器：
npm start

服务器将通过stdio启动并监听MCP命令。

Claude桌面集成

  1. 先构建项目：
npm run build

  1. 找到Claude桌面配置：

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • 视窗: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. 编辑配置文件：

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-mcp-server/dist/index.js"],
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id",
        "GMAIL_CLIENT_SECRET": "your_client_secret",
        "GMAIL_REFRESH_TOKEN": "your_refresh_token",
        "GMAIL_ALLOW_DIRECT_SEND": "false"
      }
    }
  }
}

  1. 重新启动克劳德桌面

  2. 验证连接：

    • 打开克劳德桌面
    • 寻找🔌 指示MCP连接的图标
    • 尝试：“列出我最近的电子邮件”

🛠️ 可用工具

🛡️ 安全通知：标记有的工具🛡️ 为了您的安全，默认情况下创建草稿。标记为的直接发送工具🚨 默认情况下禁用。

📬 list_邮件

列出最近使用可选过滤功能的电子邮件。

参数：

  • maxResults （数字，1-100）：最多可返回的电子邮件数（默认值：10）
  • query （string）：Gmail搜索查询（例如，“is：未读”）
  • includeSpamTrash （布尔值）：包括垃圾邮件/垃圾文件夹（默认值：false）

例子：

List my 5 most recent unread emails

📖 get_email_details

获取特定电子邮件的完整详细信息和内容。

参数：

  • emailId （字符串，必填）：要检索的电子邮件ID
  • format （string）：详细程度-“完整”、“最小”或“元数据” （默认值：“满”）

例子：

Get the full content of email ID 18abc123def

🛡️ create_draft

创建带有可选CC/BCC收件人的电子邮件草稿（建议人工智能助理使用）。

参数：

  • to （字符串，必填）：收件人电子邮件地址
  • subject （字符串，必填）：电子邮件主题
  • body （字符串，必填）：电子邮件正文（纯文本或HTML）
  • cc （字符串）：抄送收件人（逗号分隔）
  • bcc （字符串）：密件抄送收件人（逗号分隔）

例子：

Create a draft email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 10 AM"

🚨 send_email（默认禁用）

直接向可选的CC/BCC收件人发送电子邮件。

⚠️ 安全警告：默认情况下禁用此工具。集 GMAIL_ALLOW_DIRECT_SEND=true 以启用。

参数：

  • to （字符串，必填）：收件人电子邮件地址
  • subject （字符串，必填）：电子邮件主题
  • body （字符串，必填）：电子邮件正文（纯文本或HTML）
  • cc （字符串）：抄送收件人（逗号分隔）
  • bcc （字符串）：密件抄送收件人（逗号分隔）

例子：

Send an email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 10 AM"

🔍 搜索邮件

使用Gmail的高级搜索语法搜索电子邮件。

参数：

  • query （字符串，必填）：Gmail搜索查询
  • maxResults （数字，1-100）：最大结果（默认值：10）
  • includeSpamTrash （布尔值）：包括垃圾邮件/垃圾（默认值：false）

Gmail搜索查询示例：

  • from:user@example.com -来自特定发件人的电子邮件
  • subject:"important meeting" -主题中包含精确短语的电子邮件
  • has:attachment -带附件的电子邮件
  • is:unread -未读电子邮件
  • newer_than:2d -过去2天的电子邮件
  • label:work -带有特定标签的电子邮件

🛡️ find_和draft_reply

查找发件人的最新电子邮件，并创建包含可选自定义内容的草稿回复。

参数：

  • senderName （字符串，必填）：发件人姓名或电子邮件地址
  • replyBody （字符串，可选）：自定义回复内容（如果未提供，则使用模板）

例子：

Create a draft reply to the latest email from John Smith saying "Thanks for your message. I'll get back to you soon."

📚 例子

基本使用示例

列出最近的电子邮件：

Show me my 10 most recent emails

搜索特定电子邮件：

Search for emails from alice@example.com with attachments

创建电子邮件草稿：

Create a draft email to bob@example.com saying "Thanks for your help!"

创建回复草稿：

Draft a reply to the latest email from support@company.com

高级使用示例

复杂搜索：

Find all unread emails from the last week with "invoice" in the subject

与CC起草：

Create a draft email to team@company.com with CC to manager@company.com about the project update

获取电子邮件详细信息：

Show me the full content of the most recent email from my boss

🔧 故障排除

常见问题及解决方法

❌ 错误：缺少必需的环境变量

解决方案： 确保在您的 .env 文件：

  • GMAIL_CLIENT_ID
  • GMAIL_CLIENT_SECRET
  • GMAIL_REFRESH_TOKEN
  • GMAIL_ALLOW_DIRECT_SEND （可选，默认为 false)
  • OAUTH_REDIRECT_PORT （可选，默认为 8765)

❌ 错误：redirect_uri_mismatch

问题： OAuth设置失败，原因是“请求中的重定向URI与OAuth客户端授权的URI不匹配。”

解决方案：

  1. 转到谷歌云控制台→ API和服务→ 凭证
  2. 点击您的OAuth客户端
  3. 在“授权重定向URI”中，确保您拥有： http://localhost:8765/oauth2callback
  4. 如果使用自定义端口，请添加： http://localhost:YOUR_PORT/oauth2callback
  5. 确保你的 .env 文件具有匹配项 OAUTH_REDIRECT_PORT=8765
  6. 重要：OAuth客户端必须 Web应用程序 类型，而非桌面应用

当遵循建议使用“桌面应用程序”类型的旧文档时，通常会出现此错误，该类型不支持自定义重定向URI。

🛡️ 安全：已禁用直接电子邮件发送

这是正常和安全的行为。 默认情况下，服务器创建草稿，而不是直接发送电子邮件。

解决：

  • 推荐：使用 create_draft 工具而不是 send_email
  • 替代：设置 GMAIL_ALLOW_DIRECT_SEND=true 在你的 .env 文件（不建议用于AI助手）

❌ 错误403：已访问

解决方案：

  1. 转到谷歌云控制台→ OAuth同意屏幕
  2. 将您的电子邮件添加为测试用户
  3. 重新运行令牌生成过程

❌ 错误：invalid_grant

解决方案： 您的刷新令牌已过期或无效

  1. 从中删除旧的刷新令牌 .env
  2. 跑 npm run setup 再次
  3. 完成授权流程
  4. 更新 .env 使用新令牌

❌ Gmail API未启用

解决方案：

  1. 转到谷歌云控制台
  2. 导航到API和服务→ 图书馆
  3. 搜索“Gmail API”
  4. 单击启用

❌ Claude Desktop未显示MCP服务器

解决方案：

  1. 验证配置文件路径是否正确
  2. 确保配置中的所有路径都是绝对路径
  3. 检查构建文件是否存在于 dist/
  4. 完全重新启动克劳德桌面
  5. 检查Claude Desktop日志是否有错误

❌ 请求频率超限

解决方案：

  • Gmail API有配额（每个用户每秒250个配额单位）
  • 实现重试的指数回退
  • 减少并行请求的数量

🔒 安全指南

第一种方法草案

此服务器实现了 安全第一设计 为了防止意外的电子邮件发送：

  • 默认行为：创建需要手动审阅的草稿
  • 保护: send_email 默认情况下，该工具处于禁用状态
  • 用户控制：直接发送所需的显式环境变量

推荐使用方法

✅ 对AI助手安全：

  • create_draft -创建电子邮件草稿
  • find_and_draft_reply -创建回复草稿
  • list_emails, search_emails, get_email_details -只读操作

⚠️ 小心使用：

  • send_email -只有在您完全信任AI助手并了解风险的情况下才能启用

最佳实践

  1. 保持 GMAIL_ALLOW_DIRECT_SEND=false 除非绝对必要
  2. 审阅所有草稿 从Gmail手动发送之前
  3. 彻底测试 在生产使用前的安全环境中
  4. 监控使用情况 并检查是否有意外行为

🔨 发展

可用脚本

# Development with hot reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Start production server
npm start

# Generate OAuth refresh token
npm run setup

# Run tests
npm test

# Lint code
npm run lint

项目结构

gmail-mcp-server/
├── src/
│   ├── index.ts                 # Main server implementation
│   └── get-refresh-token-desktop.ts # OAuth setup utility
├── dist/                        # Compiled JavaScript (generated)
├── examples/                    # Usage examples
├── docs/                       # Additional documentation
├── .env.example                # Environment variables template
├── tsconfig.json              # TypeScript configuration
├── package.json              # Project dependencies
└── README.md                # This file

测试

测试连接和基本功能：

# Test Gmail connection
npm run dev test-gmail-connection.ts

# Test with MCP client
npm run dev test-list-emails.js

🤝 贡献

欢迎投稿！请随时提交拉取请求。

  1. 分叉存储库
  2. 创建功能分支(git checkout -b feature/AmazingFeature)
  3. 提交您的更改(git commit -m 'Add some AmazingFeature')
  4. 推到分支(git push origin feature/AmazingFeature)
  5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件 了解详情。

🙏 致谢

📞 支持

对于问题、疑问或建议：

由以下材料制成❤️ 靠近 贾维·佩莱

相关 MCP