内容
# Gmail MCP 服务器
一个连接模型上下文协议（MCP）到Gmail的Node.js服务器，使大型语言模型能够使用Gmail API安全地发送、读取和管理电子邮件。
<p align="center">
<a href="https://github.com/nisalgunawardhana/Gmail-MCP-Server/watchers">
<img src="https://img.shields.io/github/watchers/nisalgunawardhana/Gmail-MCP-Server?style=social" alt="Watchers"/>
</a>
<a href="https://github.com/nisalgunawardhana/Gmail-MCP-Server/stars">
<img src="https://img.shields.io/github/stars/nisalgunawardhana/Gmail-MCP-Server?style=social" alt="Stars"/>
</a>
<a href="https://github.com/nisalgunawardhana/Gmail-MCP-Server/network/members">
<img src="https://img.shields.io/github/forks/nisalgunawardhana/Gmail-MCP-Server?style=social" alt="Forks"/>
</a>
</p>
## 功能
- 📤 通过Gmail API发送电子邮件
- 📥 获取收件箱邮件，支持筛选选项
- 🔍 使用Gmail查询语法进行高级邮件搜索
- 📧 通过ID检索特定邮件，包含完整内容
- 📝 访问草稿邮件
- 📬 查看已发送邮件
- 📎 支持HTML和纯文本邮件
- 📁 附件支持（发送和查看）
- 👥 CC和BCC收件人
- 🔐 Google OAuth2身份验证
- 🛡️ 安全的凭证管理
- ⚡ 快速的电子邮件操作，支持元数据缓存
## 安装
### 1. 安装依赖
```bash
npm install
```
### 2. Google Cloud设置
1. 访问 [Google Cloud Console](https://console.cloud.google.com/)
2. 创建新项目或选择现有项目
3. 启用Gmail API：
- 进入 "APIs & Services" > "Library"
- 搜索 "Gmail API" 并启用它
4. 创建凭证：
- 进入 "APIs & Services" > "Credentials"
- 点击 "Create Credentials" > "OAuth 2.0 Client IDs"
- 选择 "Desktop application"
- 下载JSON文件并重命名为 `credentials.json`
- 将其放在项目的根目录中
**注意**：桌面应用程序自动适用于带外身份验证流程，因此不需要额外的重定向URI配置。
5. 配置OAuth同意屏幕：
- 进入 "APIs & Services" > "OAuth consent screen"
- 选择 "External" 用户类型（除非您有Google Workspace）
- 填写必填字段：
- 应用名称："Gmail MCP Server"（或您喜欢的名称）
- 用户支持邮箱：您的邮箱地址
- 开发人员联系信息：您的邮箱地址
- 将您的Gmail地址添加到 "Test users" 部分
- 这允许您在测试模式下使用应用
### 3. 身份验证设置
完成OAuth身份验证，允许服务器发送电子邮件：
```bash
npm run setup
```
这将：
1. 检查 `credentials.json` 是否存在
2. 生成授权URL
3. 引导您完成OAuth流程
4. 保存身份验证令牌
#### 🔍 查找授权码
在Google OAuth屏幕点击 "Allow" 后，您将被重定向。以下是查找授权码的方法：
**方法1：直接代码显示（最常见于桌面应用）**
- 点击 "Allow" 后，Google会直接显示授权码
- 查找类似 "Please copy this code, switch to your application and paste it there:" 的文本
- 从文本框或高亮区域复制代码
**示例授权码：**
```
4/0AbCD1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890
```
⚠️ **重要**：代码通常很长（50+字符），以 `4/0` 开头
**注意**：服务器直接从 `credentials.json` 读取OAuth凭证。除非您想设置可选配置，否则不需要创建 `.env` 文件。
### 可选：环境配置
您可以可选地创建 `.env` 文件以设置附加配置：
```env
# 可选：默认发件人邮箱（如果未设置，将使用身份验证用户的邮箱）
DEFAULT_SENDER_EMAIL=your-email@gmail.com
# 可选：授权码（用于自动化设置）
AUTH_CODE=your_auth_code_here
```
运行服务器第一次以完成OAuth身份验证：
```bash
npm start
```
按照浏览器中的身份验证流程，并在提示时粘贴授权码。
## 使用
### MCP客户端配置
将此服务器添加到MCP客户端配置中：
```json
{
"mcpServers": {
"gmail": {
"command": "node",
"args": ["/path/to/gmail-mcp-server/src/index.js"],
"env": {}
}
}
}
```
### 可用工具
#### send_email
通过Gmail发送电子邮件。
**参数：**
- `to` （必填）：收件人邮箱地址（字符串或字符串数组）
- `subject` （必填）：邮件主题行
- `body` （必填）：邮件正文内容
- `cc` （可选）：CC收件人邮箱地址（字符串或字符串数组）
- `bcc` （可选）：BCC收件人邮箱地址（字符串或字符串数组）
- `html` （可选）：设置为true如果正文包含HTML内容（默认：false）
- `attachments` （可选）：要附加的文件路径数组
**示例：**
```json
{
"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_inbox_emails
检索收件箱邮件，可选筛选。
**参数：**
- `maxResults` （可选）：要检索的最大邮件数量（默认：10）
- `query` （可选）：Gmail搜索查询以筛选邮件（默认："in:inbox"）
- `includeSpamTrash` （可选）：包括垃圾邮件和回收站邮件（默认：false）
**示例：**
```json
{
"name": "get_inbox_emails",
"arguments": {
"maxResults": 5,
"query": "is:unread"
}
}
```
#### get_email_by_id
通过ID获取特定邮件，包含完整内容。
**参数：**
- `emailId` （必填）：要检索的邮件ID
- `format` （可选）：邮件数据格式 - "full", "metadata", 或 "minimal" （默认："full"）
**示例：**
```json
{
"name": "get_email_by_id",
"arguments": {
"emailId": "1234567890abcdef",
"format": "full"
}
}
```
#### search_emails
使用Gmail强大的搜索查询语法搜索邮件。
**参数：**
- `query` （必填）：Gmail搜索查询（例如："from:example@gmail.com", "subject:important", "has:attachment"）
- `maxResults` （可选）：要检索的最大邮件数量（默认：10）
**示例：**
```json
{
"name": "search_emails",
"arguments": {
"query": "from:boss@company.com has:attachment",
"maxResults": 20
}
}
```
#### get_sent_emails
检索已发送邮件。
**参数：**
- `maxResults` （可选）：要检索的最大邮件数量（默认：10）
**示例：**
```json
{
"name": "get_sent_emails",
"arguments": {
"maxResults": 15
}
}
```
#### get_draft_emails
检索草稿邮件。
**参数：**
- `maxResults` （可选）：要检索的最大草稿邮件数量（默认：10）
**示例：**
```json
{
"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调用都使用Google的官方Gmail API，并具有正确的身份验证
## 故障排除
### "Insufficient Permission" 错误
**这是从仅发送邮件升级到完整邮件访问时最常见的问题。**
**快速修复：**
```bash
# 删除旧令牌并重新身份验证
rm token.json
npm run setup
```
**或使用专用重新身份验证脚本：**
```bash
npm run reauth
```
**为什么会发生这种情况：**原始身份验证仅请求 `gmail.send` 权限。新功能需要额外的范围（`gmail.readonly` 和 `gmail.modify` ）。
### OAuth 403：access_denied 错误
如果您遇到 "Error 403: access_denied" 或 "app is currently being tested"，请按照以下步骤：
#### 快速修复（推荐个人使用）：
1. **将自己添加为测试用户**：
- 访问 [Google Cloud Console](https://console.cloud.google.com/)
- 导航到 "APIs & Services" > "OAuth consent screen"
- 向下滚动到 "Test users" 部分
- 点击 "ADD USERS" 并添加您的Gmail地址
- 保存更改
2. **确保正确的用户类型**：
- 在OAuth同意屏幕中，确保您选择了 "External" 用户类型
- 如果您选择了 "Internal" 但没有Google Workspace，请更改为 "External"
3. **清除浏览器缓存并重试**：
- 清除Google账户的浏览器缓存和cookie
- 再次尝试身份验证流程
#### 替代方案：使用应用密码（Gmail特定）
如果OAuth继续出现问题，您可以使用Gmail应用密码：
1. **启用2-Factor Authentication** 您的Google账户
2. **生成应用密码**：
- 访问Google账户设置
- 安全 > 2-Step Verification > App passwords
- 为 "Mail" 生成密码
3. **使用SMTP而不是Gmail API** （需要代码修改）
#### 生产使用：
要永久移除测试限制：
1. 完成OAuth同意屏幕的所有必填信息
2. 提交Google验证（需要1-4周）
3. 提供隐私政策、服务条款和应用首页
4. 验证后，任何Gmail用户都可以授权您的应用
### 其他常见问题
#### "credentials.json not found"
- 确保文件位于项目根目录
- 检查文件名是否为 `credentials.json`
- 验证文件是否包含有效JSON
#### "Token refresh failed"
- 删除 `token.json` 文件
- 运行 `npm run setup` 重新身份验证
- 确保您的OAuth2凭证仍然有效
#### "Gmail API not enabled"
- 访问Google Cloud Console
- 导航到 "APIs & Services" > "Library"
- 搜索 "Gmail API" 并确保已启用
## 🔄 重要：邮件阅读需要重新身份验证
**如果您以前仅设置了此服务器发送邮件**，您需要重新身份验证以访问收件箱和邮件阅读功能。原始设置仅请求 `gmail.send` 权限，但新功能需要额外的范围。
### 快速修复：
1. **删除现有令牌**：
```bash
rm token.json
```
2. **重新运行设置**（此操作将请求额外的权限）：
```bash
npm run setup
```
3. **再次遵循OAuth流程** - 这次它将请求权限：
- 发送邮件（`gmail.send`）
- 读取邮件（`gmail.readonly`)
- 修改邮件（`gmail.modify`）
### 替代：强制重新身份验证脚本
如果您更喜欢专用脚本：
```bash
npm run reauth
```
## 开发
```bash
# 启动自动重新加载
npm run dev
# 运行测试
npm run test
## 贡献
我们欢迎为Gmail MCP Server做出贡献！以下是您可以帮助的方式：
### 🚀 开始
1. **Fork存储库** 在GitHub
2. **克隆您的fork** 本地：
```bash
git clone https://github.com/your-username/email-mcp-server.git
cd email-mcp-server
```
3. **安装依赖**：
```bash
npm install
```
4. **设置身份验证**（参见上面的设置部分）：
```bash
npm run setup
```
### 🔧 开发工作流
1. **创建功能分支**：
```bash
git checkout -b feature/your-feature-name
```
2. **进行更改** 遵循我们的编码标准
3. **测试您的更改**：
```bash
npm run test
```
4. **本地运行服务器** 以验证功能：
```bash
npm run dev
```
5. **提交您的更改** 并附有描述性消息：
```bash
git commit -m "feat: add support for email labels"
```
6. **推送到您的fork**：
```bash
git push origin feature/your-feature-name
```
7. **创建Pull Request** 在GitHub
### 📝 编码标准
- **JavaScript风格**：使用现代ES6+语法
- **格式**：运行 `npm run lint` （如果可用）提交前
- **注释**：为函数和复杂逻辑添加JSDoc注释
- **错误处理**：始终包含正确的错误处理和验证
- **安全**：永远不要日志或暴露敏感凭证
### 🧪 测试指南
- **编写测试** 在 `test/` 目录中的新功能
- **测试邮件功能** 使用提供的测试脚本：
```bash
node test/send-test-email.js
node test/email-operations-test.js
```
- **验证MCP集成** 使用测试客户端：
```bash
node test/mcp-test-client.js
```
### 📋 我们正在寻找
**高优先级：**
- 📎 增强附件处理（多个文件，大小限制）
- 🏷️ 邮件标签管理（创建、应用、删除标签）
- 📤 草稿管理（创建、编辑、发送草稿）
- 🔄 实时邮件通知 via webhooks
- 📊 邮件分析报告功能
**优先级中限：
- 🎨 HTML邮件模板支持
- 📋 邮件签名管理
- 🔍 高级搜索过滤器
- 📱 移动友好身份验证流程
- 🌐 多语言支持
**始终欢迎：**
- 🐛 错误修复和安全改进
- 📚 文档增强
- ⚡ 性能优化
- 🧪 额外的测试覆盖
### 🐛 报告问题
报告bug时，请包括：
1. **清晰的描述** 问题描述
2. **步骤以重现** 问题
3. **预期行为**：应该发生什么
4. **实际行为**：实际发生的情况
5. **错误信息** 或日志（删除敏感信息）
6. **代码片段** 如果相关
### 问题模板
我们提供问题模板，帮助您有效地报告错误和请求功能：
#### 🐛 错误报告模板
使用此模板报告错误或意外行为：
- **摘要**：简要描述问题
- **环境**：Node.js 版本，操作系统，npm 版本
- **步骤以重现**：重现问题的编号步骤
- **预期行为**：应该发生什么
- **实际行为**：实际发生的情况
- **错误信息**：任何错误日志或消息
- **附加上下文**：截图、代码片段或其他相关信息
#### ✨ 功能请求模板
使用此模板建议新功能：
- **功能摘要**：简要描述拟议的功能
- **问题陈述**：它解决了什么问题？
- **拟议解决方案**：该功能应该如何工作？
- **用例**：该功能在现实场景中的相关示例
- **替代方案**：您考虑过的其他解决方案
- **附加上下文**：草图、示例或参考
#### 📚 文档问题模板
使用此模板进行文档改进：
- **文档部分**：需要改进的部分
- **问题描述**：不清楚或缺失的内容
- **建议改进**：如何使其更好
- **目标受众**：谁会受益于此更改
#### 🔧 如何创建问题
1. **访问问题页面**：前往存储库的 [问题选项卡](https://github.com/nisalgunawardhana/email-mcp-server/issues)
2. **点击“新建问题”**：开始创建新问题
3. **选择模板**：选择合适的模板（错误报告、功能请求等）
4. **填写模板**：完成所有相关部分
5. **添加标签**：应用适当的标签（错误、增强、文档等）
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` - 安全相关问题
#### 🔍 创建问题前
**先搜索**：检查是否有人已经报告了相同的问题或请求了相同的功能。
**对于错误：**
- 尝试最新版本，看看问题是否已经修复
- 检查README中的故障排除部分
- 如果可能的话，使用不同的配置进行测试
**对于功能：**
- 考虑该功能是否符合项目的范围和目标
- 思考它将如何影响现有功能
- 寻找相关项目中的类似功能
### 💡 功能请求
对于新功能：
1. **检查现有问题** 以避免重复
2. **描述用例** 和其价值
3. **提供示例** 说明其工作原理
4. **考虑向后兼容性**
### 🏷️ 提交信息格式
我们遵循传统的提交信息格式：
```
type(scope): description
[optional body]
[optional footer]
```
**类型：**
- `feat`：新功能
- `fix`：错误修复
- `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许可协议授权。
### 🤝 行为准则
- 尊重和包容
- 关注建设性反馈
- 帮助他人学习和成长
- 遵循黄金法则
### ❓ 问题？
- 为代码库中的问题创建问题
- 检查现有文档
- 请明确您试图实现的目标
## 👤 作者
**尼萨尔·古纳瓦尔达纳**
- [GitHub](https://github.com/nisalgunawardhana) [](https://github.com/nisalgunawardhana)
- [Twitter/X](https://twitter.com/thenisal)
- [LinkedIn](https://www.linkedin.com/in/nisalgunawardhana/)
随意联系或关注以获取更新和新项目！
感谢您为Gmail MCP Server做出贡献！ 🚀
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器