AI导哈

Gmail MCP服务器

一个Node.js服务器，连接模型上下文协议（MCP）和Gmail，使大型语言模型能够通过Gmail API安全地发送、阅读和管理电子邮件。

  • by nisalgunawardhana
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 nisalgunawardhana/Gmail-MCP-Server

使用说明

Gmail MCP服务器

Node.js服务器，将模型上下文协议（MCP）连接到Gmail，使大型语言模型能够使用Gmail API安全地发送、读取和管理电子邮件。

特性

  • 📤 通过Gmail API发送电子邮件
  • 📥 使用筛选选项获取收件箱电子邮件
  • 🔍 使用Gmail查询语法进行高级电子邮件搜索
  • 📧 按ID检索包含完整内容的特定电子邮件
  • 📝 访问电子邮件草稿
  • 📬 查看已发送的电子邮件
  • 📎 支持HTML和纯文本电子邮件
  • 📁 附件支持（发送和查看）
  • 👥 CC和BCC收件人
  • 🔐 使用Google进行OAuth2身份验证
  • 🛡️ 安全的凭证管理
  • ⚡ 具有元数据缓存的快速电子邮件操作

设置

1.安装依赖项

npm install

2.谷歌云设置

  1. 转到 谷歌云控制台

  2. 创建新项目或选择现有项目

  3. 启用Gmail API：

    • 转到“API和服务”>“库”
    • 搜索“Gmail API”并启用它

  4. 创建凭据：

    • 转到“API和服务”>“凭据”
    • 点击“创建凭据”>“OAuth 2.0客户端ID”
    • 选择“桌面应用程序”
    • 下载JSON文件并将其重命名为 credentials.json
    • 将其放置在此项目的根目录中

    备注：桌面应用程序自动使用带外身份验证流，因此不需要额外的重定向URI配置。

  5. 配置OAuth同意屏幕：

    • 转到“API和服务”>“OAuth同意屏幕”
    • 选择“外部”用户类型（除非您有谷歌工作区）
    • 填写必填字段：
      • 应用程序名称：“Gmail MCP服务器”（或您的首选名称）
      • 用户支持电子邮件：您的电子邮件地址
      • 开发者联系信息：您的电子邮件地址
    • 将您的Gmail地址添加到“测试用户”部分
    • 这允许您在测试模式下使用应用程序

3.身份验证设置

完成OAuth身份验证以允许服务器发送电子邮件：

npm run setup

这将：

  1. 检查一下 credentials.json 存在
  2. 生成授权URL
  3. 引导您完成OAuth流程
  4. 保存身份验证令牌

🔍 查找您的授权码

在Google OAuth屏幕中单击“允许”后，您将被重定向。以下是如何查找您的授权码：

方法1：直接代码显示（最常见于桌面应用程序）

  • 点击“允许”后，谷歌直接在页面上显示授权码
  • 查找类似“请复制此代码，切换到您的应用程序并将其粘贴到那里：”的文本
  • 从文本框或突出显示的区域复制代码

授权代码示例：

4/0AbCD1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

⚠️ 重要：代码通常很长（50+个字符），以 4/0

备注：服务器直接从以下位置读取OAuth凭据 credentials.json。您不需要创建 .env 文件，除非您想设置可选配置。

可选：环境配置

您可以选择创建 .env 其他设置文件：

# Optional: Default sender email (will use authenticated user's email if not set)
DEFAULT_SENDER_EMAIL=your-email@gmail.com

# Optional: Authorization code (for automated setup)
AUTH_CODE=your_auth_code_here

首次运行服务器以完成OAuth身份验证：

npm start

按照浏览器中的身份验证流程进行操作，并在提示时粘贴授权码。

用法

MCP客户端配置

将此服务器添加到MCP客户端配置中：

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/path/to/gmail-mcp-server/src/index.js"],
      "env": {}
    }
  }
}

可用工具

send_邮件

通过Gmail发送电子邮件。

参数：

  • to （必填）：收件人电子邮件地址-字符串或字符串数组
  • subject （必填）：电子邮件主题行
  • body （必填）：电子邮件正文内容
  • cc （可选）：CC收件人电子邮件地址-字符串或字符串数组
  • bcc （可选）：BCC收件人电子邮件地址-字符串或字符串数组
  • html （可选）：如果正文包含HTML内容，则设置为true（默认值：false）
  • attachments （可选）：要附加的文件路径数组

例子：

{
  "name": "send_email",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Hello from MCP Server",
    "body": "This is a test email sent through the Gmail MCP server.",
    "html": false
  }
}

get_box_emails

使用可选过滤功能从收件箱中检索电子邮件。

参数：

  • maxResults （可选）：要检索的最大电子邮件数（默认值：10）
  • query （可选）：用于过滤电子邮件的Gmail搜索查询（默认：“收件箱”）
  • includeSpamTrash （可选）：包括垃圾邮件和垃圾电子邮件（默认值：false）

例子：

{
  "name": "get_inbox_emails",
  "arguments": {
    "maxResults": 5,
    "query": "is:unread"
  }
}

get_email_by_id

通过ID获取包含正文和附件在内的完整内容的特定电子邮件。

参数：

  • emailId （必填）：要检索的电子邮件的ID
  • format （可选）：电子邮件数据的格式-“完整”、“元数据”或“最小”（默认值：“完整”）

例子：

{
  "name": "get_email_by_id",
  "arguments": {
    "emailId": "1234567890abcdef",
    "format": "full"
  }
}

搜索邮件

使用Gmail强大的搜索查询语法搜索电子邮件。

参数：

  • query （必填）：Gmail搜索查询（例如，“发件人：example@gmail.com“，”主题：重要“，”有：附件“）
  • maxResults （可选）：要检索的最大电子邮件数（默认值：10）

例子：

{
  "name": "search_emails",
  "arguments": {
    "query": "from:boss@company.com has:attachment",
    "maxResults": 20
  }
}

get_sent_emails

从您的已发送文件夹中检索电子邮件。

参数：

  • maxResults （可选）：要检索的最大电子邮件数（默认值：10）

例子：

{
  "name": "get_sent_emails",
  "arguments": {
    "maxResults": 15
  }
}

get_draft_emails

检索电子邮件草稿。

参数：

  • maxResults （可选）：要检索的最大草稿电子邮件数（默认值：10）

例子：

{
  "name": "get_draft_emails",
  "arguments": {
    "maxResults": 5
  }
}

Gmail搜索查询示例

这 search_emails 和 get_inbox_emails 工具支持Gmail强大的搜索语法：

  • from:sender@example.com -来自特定发件人的电子邮件
  • to:recipient@example.com -发送给特定收件人的电子邮件
  • subject:keyword -主题中包含关键字的电子邮件
  • has:attachment -带附件的电子邮件
  • is:unread -未读电子邮件
  • is:important -重要电子邮件
  • newer_than:7d -超过7天的电子邮件
  • older_than:1m -超过1个月的电子邮件
  • size:larger_than:10M -大于10MB的电子邮件

您可以组合多个条件：

  • from:boss@company.com is:unread has:attachment
  • subject:meeting newer_than:3d
  • to:me filename:pdf older_than:1w

安全说明

  • OAuth2令牌存储在本地 token.json
  • 永不承诺 credentials.json, token.json，或 .env 文件到版本控制
  • 服务器需要用户明确同意才能访问Gmail
  • 所有API呼叫都使用谷歌官方的Gmail API，并进行正确的身份验证

故障排除

“权限不足”错误

这是从仅发送升级到完全电子邮件访问时最常见的问题。

快速修复：

# Delete old token and re-authenticate
rm token.json
npm run setup

或者使用专用的重新认证脚本：

npm run reauth

为什么会发生这种情况： 仅请求原始身份验证 gmail.send 许可。新的电子邮件阅读功能需要额外的作用域(gmail.readonly 和 gmail.modify).

OAuth 403:访问错误

如果您遇到“错误403:access_denied”或“应用程序当前正在测试中”，请按照以下步骤操作：

快速修复（建议个人使用）：

  1. 将自己添加为测试用户:

    • 首选 谷歌云控制台
    • 导航到“API和服务”>“OAuth同意屏幕”
    • 向下滚动到“测试用户”部分
    • 点击“添加用户”并添加您的Gmail地址
    • 保存更改

  2. 确保用户类型正确:

    • 在OAuth同意屏幕中，确保您选择了“外部”用户类型
    • 如果您选择了“内部”但没有谷歌工作区，请更改为“外部”

  3. 清除浏览器缓存，然后重试:

    • 清除浏览器缓存和Google帐户的Cookie
    • 请重试身份验证流程

替代方案：使用应用程序密码（特定于Gmail）

如果OAuth仍然存在问题，您可以使用Gmail应用程序密码：

  1. 启用双因素身份验证 在您的Google帐户上
  2. 生成应用程序密码:
    • 转到Google帐户设置
    • 安全>两步验证>应用密码
    • 为“邮件”生成密码
  3. 使用SMTP而不是Gmail API （需要修改代码）

用于生产用途：

要永久取消测试限制：

  1. 使用所有必需的信息完成OAuth同意屏幕
  2. 提交谷歌验证（需要1-4周）
  3. 提供隐私政策、服务条款和应用程序主页
  4. 验证后，任何Gmail用户都可以授权您的应用程序

其他常见问题

“未找到credentials.json”

  • 确保文件位于项目根目录中
  • 检查文件名是否准确 credentials.json
  • 验证文件是否包含有效的JSON

“令牌刷新失败”

  • 删除 token.json 文件
  • 跑 npm run setup 重新验证
  • 确保您的OAuth2凭据仍然有效

“未启用Gmail API”

  • 转到谷歌云控制台
  • 导航到“API和服务”>“库”
  • 搜索“Gmail API”并确保其已启用

🔄 重要提示：阅读电子邮件需要重新验证

如果您之前将此服务器设置为仅发送电子邮件，您需要重新验证才能访问收件箱和电子邮件阅读功能。仅请求了原始设置 gmail.send 权限，但新功能需要额外的作用域。

快速修复“权限不足”错误：

  1. 删除现有令牌:

    rm token.json

  2. 重新运行安装程序 （这将请求额外的权限）：

    npm run setup

  3. 再次遵循OAuth流程 -这次它将请求以下权限：

    • 发送电子邮件(gmail.send)
    • 阅读电子邮件(gmail.readonly)
    • 修改电子邮件(gmail.modify)

替代方案：强制重新身份验证脚本

如果您更喜欢专用脚本：

npm run reauth

发展

# Start with auto-reload
npm run dev

# Run tests
npm run test

贡献

我们欢迎对Gmail MCP服务器的贡献！以下是您可以提供帮助的方式：

🚀 入门指南

  1. 分叉存储库 在GitHub上
  2. 克隆你的叉子 本地：
    git clone https://github.com/your-username/email-mcp-server.git
cd email-mcp-server
  3. 安装依赖项:
    npm install
  4. 设置身份验证 （请参阅上面的设置部分）：
    npm run setup

🔧 开发工作流程

  1. 创建要素分支:
    git checkout -b feature/your-feature-name
  2. 进行更改 遵循我们的编码标准
  3. 测试您的更改:
    npm run test
  4. 在本地运行服务器 验证功能：
    npm run dev
  5. 提交您的更改 带有描述性信息：
    git commit -m "feat: add support for email labels"
  6. 推你的叉子:
    git push origin feature/your-feature-name
  7. 创建拉取请求 在GitHub上

📝 编码标准

  • JavaScript样式：使用现代ES6+语法
  • 格式化：运行 npm run lint （如有）在承诺之前
  • 评论：为函数和复杂逻辑添加JSDoc注释
  • 错误处理：始终包括正确的错误处理和验证
  • 安全：切勿记录或公开敏感凭据

🧪 测试指南

  • 编写测试 对于中的新功能 test/ 目录
  • 测试电子邮件功能 使用提供的测试脚本：
    node test/send-test-email.js
node test/email-operations-test.js
  • 验证MCP集成 使用测试客户端：
    node test/mcp-test-client.js

📋 我们正在寻找什么

高优先级：

  • 📎 增强的附件处理（多个文件，大小限制）
  • 🏷️ 电子邮件标签管理（创建、应用、删除标签）
  • 📤 草稿管理（创建、编辑、发送草稿）
  • 🔄 通过webhooks实时发送电子邮件通知
  • 📊 电子邮件分析和报告功能

中等优先级：

  • 🎨 HTML电子邮件模板支持
  • 📋 电子邮件签名管理
  • 🔍 高级搜索过滤器和排序
  • 📱 移动友好的身份验证流程
  • 🌐 多语言支持

欢迎光临：

  • 🐛 Bug修复和安全改进
  • 📚 文档增强
  • ⚡ 性能优化
  • 🧪 附加测试覆盖率

🐛 报告问题

报告错误时，请包括：

  1. 清晰的描述 关于这个问题
  2. 重现步骤 问题
  3. 预期行为与实际行为
  4. 环境详细信息:
    • Node.js版本(node --version)
    • npm版本(npm --version)
    • 操作系统
  5. 错误消息 或日志（删除敏感信息）
  6. 代码片段 如果相关

📋 问题模板

我们提供问题模板，以帮助您有效地报告错误和请求功能：

🐛 Bug报告模板

报告错误或意外行为时使用此模板：

  • 总结：问题的简要说明
  • 环境：Node.js版本、操作系统、npm版本
  • 重现问题的步骤：重新创建问题的编号步骤
  • 预期行为：应该发生什么
  • 实际行为：实际发生了什么
  • 错误消息：任何错误日志或消息
  • 附加上下文：屏幕截图、代码片段或其他相关信息

✨ 功能请求模板

建议新功能时使用此模板：

  • 功能摘要：拟议功能的简要说明
  • 问题陈述：这解决了什么问题？
  • 建议的解决方案：此功能应如何工作？
  • 用例：这将有所帮助的真实世界场景
  • 考虑的替代方案：您考虑过的其他解决方案
  • 附加上下文：模型、示例或参考

📚 文档发布模板

使用此模板改进文档：

  • 文件科：哪个部分需要改进
  • 问题描述：什么不清楚或缺失
  • 建议改进：如何让它变得更好
  • 目标受众：谁将从这一变化中受益

🔧 如何创建问题

  1. 访问问题页面：转到存储库的 问题选项卡
  2. 点击“新问题”：开始创建新问题
  3. 选择模板：选择合适的模板（Bug报告、功能请求等）
  4. 填写模板：完成所有相关章节
  5. 添加标签：应用适当的标签（bug、增强、文档等）
  6. 提交：单击“提交新问题”

📝 问题标签指南

我们使用这些标签对问题进行分类：

类型标签：

  • bug -有些东西不起作用
  • enhancement -新功能或请求
  • documentation -文件的改进或补充
  • question -要求提供更多信息
  • help wanted -需要额外注意
  • good first issue -对新人有好处

优先级标签：

  • priority: high -需要立即关注的关键问题
  • priority: medium -应尽快解决的重要问题
  • priority: low -很高兴有改进

组件标签：

  • gmail-api -与Gmail API集成相关
  • authentication -OAuth和凭据管理
  • mcp -模型上下文协议功能
  • testing -测试相关问题
  • security -安全相关问题

🔍 创建问题之前

先搜索：检查是否有人已经报告了相同的问题或请求了相同的功能。

对于Bug：

  • 尝试最新版本，查看问题是否已修复
  • 查看README中的故障排除部分
  • 如果可能，使用不同的配置进行测试

功能：

  • 考虑这是否符合项目的范围和目标
  • 思考它将如何影响现有功能
  • 在相关项目中查找类似功能

💡 功能请求

有关新功能：

  1. 检查现有问题 避免重复
  2. 描述用例 以及为什么它很有价值
  3. 提供示例 它将如何工作
  4. 考虑向后兼容性

🏷️ 提交消息格式

我们遵循常规承诺：

type(scope): description

[optional body]

[optional footer]

类型：

  • feat：新功能
  • fix：Bug修复
  • docs：文件更改
  • style：代码样式更改（无逻辑更改）
  • refactor：代码重构
  • test：添加或更新测试
  • chore：维护任务

示例：

feat(gmail): add support for email labels
fix(auth): handle token refresh edge case
docs(readme): update API documentation
test(email): add unit tests for validation

📄 许可证

通过贡献，您同意您的贡献将根据MIT许可证获得许可。

🤝 行为准则

  • 尊重他人，包容他人
  • 注重建设性反馈
  • 帮助他人学习和成长
  • 遵循黄金法则

❓ 问题？

  • 打开一个问题来回答有关代码库的问题
  • 首先检查现有文档
  • 明确你想要实现的目标

👤 作者

尼萨尔·古纳瓦德纳

欢迎随时联系或关注更新和新项目！

感谢您对Gmail MCP服务器的贡献！ 🚀

相关 MCP