使用说明

Gmail MCP服务器

实际工作的Gmail MCP服务器 -无需OpenAI API，岩石-固体身份验证，零配置麻烦

通过Claude Desktop，使用自然语言命令将您的Gmail转换为人工智能收件箱。发送电子邮件、管理标签、自动化组织、下载附件——所有这些都不需要离开你的对话。

✨ 主要亮点：

🔐 防弹认证 -具有自动刷新功能的智能令牌管理
🚀 生产就绪 -TypeScript，全面的错误处理，久经考验
💰 100%免费 -没有OpenAI API成本，没有隐藏费用
🔒 隐私第一 -直接Gmail API，无第三方人工智能依赖
📦 功能完整 -附件、标签、过滤器、批处理操作等

为什么选择这个而不是其他选择？ | 看看它在行动 | 5分钟后开始

📚 文档

完整的API参考资料 -所有工具的详细文档
故障排除指南 -常见问题的解决方案
示例用例 -实例和工作流程
与备选方案的比较 -为什么选择此服务器
展示 -看看你能建造什么
贡献指南 -如何做出贡献
行为准则 -社区指南
安全策略 -安全最佳实践
更新日志 -版本历史和更新

为什么是这个项目？

传统的Gmail集成在身份验证复杂性和令牌管理方面存在困难。此服务器通过以下方式解决了这些问题：

智能令牌管理：自动验证和刷新-不再有过期凭据错误
用户友好的错误处理：清晰、可操作的错误消息，并提供分步解决方案
全面的电子邮件操作：发送、阅读、搜索、组织和自动化收件箱
生产准备就绪：使用TypeScript构建，正确的错误处理和广泛的测试

快速开始

先决条件

Node.js 16或更高版本
Google Cloud Platform帐户
Claude桌面应用程序

安装

选项1：直接运行（建议用于测试）

git clone https://github.com/devdattatalele/gmail-mcp-server.git
cd gmail-mcp-server
npm install
npm run build

选项2：按包安装

npm install -g @devdattatalele/gmail-mcp-server

谷歌云设置

在使用此服务器之前，您需要设置OAuth凭据：

1.创建谷歌云项目

引导到谷歌云控制台以及：

创建新项目（或选择现有项目）
启用 Gmail API 为您的项目
记下您的项目ID以备后用

2.配置OAuth同意屏幕

这是 最关键的一步 -跳过它，您将收到身份验证错误：

首选 API和服务 → OAuth同意屏幕
选择外部用户类型
填写必填字段：
- 应用程序名称：Gmail MCP服务器
- 用户支持电子邮件：您的电子邮件
- 开发人员联系电子邮件：您的电子邮件
添加这些 授权范围:
- https://www.googleapis.com/auth/gmail.modify
- https://www.googleapis.com/auth/gmail.settings.basic
将自己添加为测试用户:
- 滚动到“测试用户”部分
- 点击“添加用户”
- 输入您的Gmail地址
- 点击“保存”

关键的：如果不将自己添加为测试用户，您将在身份验证过程中遇到“错误403：访问被阻止”。

3.创建OAuth凭据

首选 API和服务 → 凭证
点击 创建凭据 → OAuth客户端ID
选择应用程序类型：
- Web应用程序 （推荐）
配置授权重定向URI：
- 添加： http://localhost:3000/oauth2callback
下载JSON凭据文件
将其重命名为 gcp-oauth.keys.json
将其放置在项目目录中或 ~/.gmail-mcp/

认证

首次设置

# Navigate to project directory
cd gmail-mcp-server

# Run authentication
node dist/index.js auth

服务器将：

显示有用的飞行前检查表
打开浏览器进行谷歌身份验证
将凭据保存到 ~/.gmail-mcp/credentials.json
根据需要自动验证和刷新令牌

重认证

如果您需要切换帐户或修复身份验证问题：

node dist/index.js auth --force

这 --force 标志会删除现有凭据并重新开始。

配置Claude桌面

将此添加到您的Claude Desktop配置文件中：

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

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

替换 /absolute/path/to/gmail-mcp-server 根据您的实际项目路径。

特性

电子邮件操作

发送和起草

发送电子邮件 带附件、CC、BCC
电子邮件草稿 供以后编辑
HTML和纯文本 支持
回复帖子 支持线程
附件处理 每封电子邮件高达25MB

阅读与搜索

阅读电子邮件 具有完整的MIME结构解析
搜索使用Gmail强大的查询语法
下载附件 到本地文件系统
查看附件元数据 （文件名、大小、类型、ID）

组织

标签管理：创建、更新、删除、列出
批量操作：高效处理多封电子邮件
邮件过滤软件：自动化收件箱组织
存档、删除、标记为已读/未读

高级功能

智能身份验证

// Automatic token validation on server start
// Auto-refresh expired tokens
// Clear error messages for common issues
// Force re-authentication option

批处理

// Process up to 50 emails at once
// Automatic retry on individual failures
// Detailed success/failure reporting

筛选器模板

常见场景的预构建模板：

按发件人自动组织
按主题关键字筛选
处理大型附件
管理邮件列表
内容过滤

API 参考

可用工具

`send_email`

立即发送电子邮件。

参数：

to （string[]）：收件人电子邮件地址
subject （string）：电子邮件主题
body （字符串）：电子邮件正文（纯文本）
htmlBody （字符串，可选）：正文的HTML版本
cc （string[]，可选）：抄送收件人
bcc （string[]，可选）：密件抄送收件人
attachments （string[]，可选）：要附加的文件路径
threadId （字符串，可选）：回复线程

例子：

{
  "to": ["colleague@example.com"],
  "subject": "Project Update",
  "body": "Here's the latest on the project...",
  "attachments": ["/path/to/report.pdf"]
}

`draft_email`

在不发送的情况下创建电子邮件草稿。

参数与 send_email.

`read_email`

按ID检索电子邮件内容。

参数：

messageId （string）：Gmail邮件ID

退货： 完整的电子邮件内容，包括标题、正文和附件信息。

`search_emails`

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

参数：

query （string）：Gmail搜索查询
maxResults （数字，可选）：最大结果（默认值：10）

查询示例：

from:boss@company.com after:2024/01/01
has:attachment subject:invoice
is:unread label:important

`modify_email`

更改电子邮件标签（移动、存档等）。

参数：

messageId （string）：Gmail邮件ID
addLabelIds （string[]，可选）：要添加的标签
removeLabelIds （string[]，可选）：要删除的标签

`delete_email`

永久删除电子邮件。

参数：

messageId （string）：Gmail邮件ID

`list_email_labels`

获取所有可用的Gmail标签（系统和用户创建）。

无需参数。

`create_label`

创建一个新的Gmail标签。

参数：

name （string）：标签名称
messageListVisibility （“显示”|“隐藏”，可选）
labelListVisibility （“标签显示”|“标签显示未读”|“标记隐藏”，可选）

`batch_modify_emails`

一次修改多封电子邮件的标签。

参数：

messageIds （string[]）：消息ID数组
addLabelIds （string[]，可选）
removeLabelIds （string[]，可选）
batchSize （数字，可选）：批量大小（默认值：50）

`batch_delete_emails`

一次删除多封电子邮件。

参数：

messageIds （string[]）：消息ID数组
batchSize （数字，可选）：批量大小（默认值：50）

`create_filter`

使用自定义条件创建Gmail筛选器。

参数：

criteria：匹配条件（从、到、主题、查询、hasAttachment、大小等）
action：要执行的操作（添加标签、删除标签、转发）

`download_attachment`

将电子邮件附件下载到本地文件系统。

参数：

messageId （string）：Gmail邮件ID
attachmentId （string）：附件ID（来自read_email）
savePath （字符串，可选）：下载目录
filename （字符串，可选）：自定义文件名

故障排除

身份验证问题

错误：“403：访问被阻止”

原因： 您的应用程序处于“测试”模式，您未被添加为测试用户。

解决方案：

访问 OAuth同意屏幕
滚动到“测试用户”
点击“添加用户”
输入您的Gmail地址
保存并重试身份验证

错误：“400:invalid_request”或“不符合OAuth 2.0策略”

原因： OAuth同意屏幕缺少必填字段（通常是隐私政策）。

解决方案：

转到OAuth同意屏幕配置
添加 隐私政策URL （可以使用 https://policies.google.com/privacy 作为占位符）
确保 开发人员联系电子邮件 已填满
保存并重试

错误：“凭据无效或已过期”

解决方案：

node dist/index.js auth --force

这将删除旧凭据并开始新的身份验证。

错误：“端口3000已在使用中”

解决方案：

# macOS/Linux
lsof -ti:3000 | xargs kill

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

操作问题

附件无法发送

可能的原因：

文件路径不正确或无法访问
文件超过Gmail的25MB限制
读取文件的权限问题

解决方案：

验证文件路径是否为绝对路径
检查文件权限
确保文件大小小于25MB

令牌刷新失败

服务器会自动刷新过期的令牌。如果失败：

检查您的互联网连接
验证OAuth凭据在Google Cloud控制台中仍然有效
跑 node dist/index.js auth --force 重新验证

发展

项目结构

gmail-mcp-server/
├── src/
│   ├── index.ts              # Main server implementation
│   ├── utl.ts                # Email utilities
│   ├── label-manager.ts      # Label operations
│   ├── filter-manager.ts     # Filter operations
│   └── evals/                # Evaluation tests
├── dist/                     # Compiled JavaScript
├── gcp-oauth.keys.json       # Your OAuth credentials (gitignored)
├── package.json
├── tsconfig.json
└── README.md

从源头构建

git clone https://github.com/devdattatalele/gmail-mcp-server.git
cd gmail-mcp-server
npm install
npm run build

在发展中奔跑

npm run dev    # Watch mode - rebuilds on changes

测试身份验证

npm run auth   # Equivalent to: node dist/index.js auth

安全考虑

OAuth凭据 存储在 ~/.gmail-mcp/ 仅具有用户权限
永不承诺 gcp-oauth.keys.json 或 credentials.json 到版本控制
令牌会自动刷新 -无需手动处理过期
附件在本地处理，从不由服务器存储
查看访问权限 定期在 Google帐号设置

贡献

欢迎投稿！以下是如何开始：

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
进行更改
构建和测试： npm run build
承诺： git commit -m 'Add amazing feature'
推： git push origin feature/amazing-feature
打开拉取请求

报告问题

发现错误或有建议？打开一个问题与：

问题的清晰描述
重现步骤
预期行为与实际行为
您的环境（操作系统、节点版本等）

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

致谢

构建使用：

支持

文档: API完整参考
故障排除: 常见问题及解决方案
示例: 实际使用案例
问题: GitHub问题
讨论: GitHub讨论
安全: 报告漏洞
电子邮件: taleledevdatta@gmail.com

明星历史

如果这个项目对你有帮助，请考虑给它一个⭐!

由以下材料制成❤️ 由Devdatta Talele撰写

特别感谢大家贡献者谁让这个项目变得更好！

使用说明

Gmail MCP服务器

📚 文档

为什么是这个项目？

快速开始

先决条件

安装

谷歌云设置

1.创建谷歌云项目

2.配置OAuth同意屏幕

3.创建OAuth凭据

认证

首次设置

重认证

配置Claude桌面

特性

电子邮件操作

发送和起草

阅读与搜索

组织

高级功能

智能身份验证

批处理

筛选器模板

API 参考

可用工具

send_email

draft_email

read_email

search_emails

modify_email

delete_email

list_email_labels

create_label

batch_modify_emails

batch_delete_emails

create_filter

download_attachment

故障排除

身份验证问题

错误：“403：访问被阻止”

错误：“400:invalid_request”或“不符合OAuth 2.0策略”

错误：“凭据无效或已过期”

错误：“端口3000已在使用中”

操作问题

附件无法发送

令牌刷新失败

发展

项目结构

从源头构建

在发展中奔跑

测试身份验证

安全考虑

贡献

报告问题

许可证

致谢

支持

明星历史

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

科学研究的开源MCP服务器

`send_email`

`draft_email`

`read_email`

`search_emails`

`modify_email`

`delete_email`

`list_email_labels`

`create_label`

`batch_modify_emails`

`batch_delete_emails`

`create_filter`

`download_attachment`