使用说明

📬️ Gmail MCP服务器

概述

这个项目是一个模型上下文协议（MCP）服务器，它使像克劳德这样的人工智能助手能够与Gmail帐户进行交互。该服务器提供阅读未读电子邮件和创建草稿回复的工具，通过自然语言对话实现无缝的电子邮件管理。

专为：MCP基金会项目评估
技术栈：Python 3.11+，Python MCP SDK，Gmail API，OAuth2
目标：Claude桌面集成（与任何MCP客户端兼容）

核心功能

电子邮件检索：从Gmail获取未读电子邮件。
草稿创建：为所选电子邮件创建草稿回复。
消息管理：将电子邮件标记为已读或未读，删除电子邮件。
人工智能辅助电子邮件起草：通过MCP资源和提示提供专业写作指南和模板。
谷歌文档集成：可选择从Google Docs获取电子邮件指南以进行集中管理。

MCP能力

工具

get_unread_emails：返回发件人、主题、正文/片段和电子邮件/线程ID
create_draft_reply：根据原始电子邮件/线程ID和回复正文创建正确的线程草稿回复

资源

file:///email-guidelines/7cs-communication.md：有效沟通的7C框架
file:///email-guidelines/personal-templates.md：11个用于常见任务的个人电子邮件模板
file:///email-guidelines/ai-drafting-directive.md：全面的人工智能电子邮件起草指令，包括人物角色和说服策略

延伸目标

1.通过MCP资源建立专业写作框架

暴露了克劳德在起草电子邮件时可以访问的三个综合资源：

7沟通 (file:///email-guidelines/7cs-communication.md)
- 确保电子邮件清晰、简洁、正确、连贯、完整、礼貌和具体的专业框架
- 使用时自动应用 draft_professional_reply 提示
个人电子邮件模板 (file:///email-guidelines/personal-templates.md)
- 11个通用场景（约会、报价、邻居通信等）的现成模板
- 可通过 suggest_template AI驱动的匹配提示
人工智能起草指令 (file:///email-guidelines/ai-drafting-directive.md)
- 结合了戴尔·卡耐基、罗伯特·恰尔迪尼和斯蒂芬·柯维的原则
- 定义角色、语气映射和道德说服策略
- 确保所有通信中的语音一致

2.先进的MCP提示与快速工程

实施了三个复杂的提示，演示了不同的提示工程技术：

提示	技术	目的
`draft_professional_reply`	思维链	专业电子邮件的7步推理过程
`schedule_meeting_reply`	上下文提示	日历集成会议日程安排
`suggest_template`	少镜头学习	基于AI的模板匹配与置信度评分

3.谷歌文档集成（可选）

直接从Google Docs获取电子邮件指南，以获取集中的、团队可共享的文档
如果Google Docs不可用，则自动回退到本地markdown文件
支持协作指南更新，无需更改代码
可通过以下方式配置 settings.toml 带有文档ID

4.谷歌日历集成（可选）

通过Google Calendar API实时查看可用性
这 schedule_meeting_reply prompt会自动提示您实际空闲的时间
遵循AI指令中的“始终提供2个时隙选项”协议

影响：这些增强功能将基本的电子邮件起草转换为一个复杂的、上下文感知的系统，在节省时间的同时保持专业标准和个人声音。

里程碑

核心要求

[x] Gmail API设置：谷歌云项目，OAuth2配置，范围
[x] MCP服务器：使用mcp SDK实现Python
[x] 授权：Gmail API的OAuth2身份验证
[x] 电子邮件检索工具: get_unread_emails 带有必填字段
[x] 草稿回复工具: create_draft_reply 带螺纹
[x] Claude桌面集成：本地服务器配置和测试
[x] 文档：设置说明、示例提示、屏幕截图

快速开始

先决条件

Python 3.11+
启用Gmail API的谷歌云项目
OAuth2凭据（不是应用程序密码）
克劳德桌面版

Gmail API设置

创建谷歌云项目
启用Gmail API
配置OAuth2（作用域：gmail.readonly、gmail.compose）
下载credentials.json

Claude桌面配置

步骤1：找到您的配置文件

配置文件的位置取决于您的操作系统：

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

步骤2：添加MCP服务器配置

将此添加到您的 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "gmail_mcp_server": {
      "command": "/Users/YOUR_USERNAME/path/to/gmail-mcp/.venv/bin/python",
      "args": ["/Users/YOUR_USERNAME/path/to/gmail-mcp/main.py"]
    }
  }
}

重要：将路径替换为实际的绝对路径：

查找您的项目目录： pwd （在gmailmcp目录中时）
更新两者 command 路径（到.vnv中的Python）和 args 路径（到main.py）

示例（macOS）:

{
  "mcpServers": {
    "gmail_mcp_server": {
      "command": "/Users/johndoe/projects/gmail-mcp/.venv/bin/python",
      "args": ["/Users/johndoe/projects/gmail-mcp/main.py"]
    }
  }
}

示例（Windows）:

{
  "mcpServers": {
    "gmail_mcp_server": {
      "command": "C:\\Users\\johndoe\\projects\\gmail-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\johndoe\\projects\\gmail-mcp\\main.py"]
    }
  }
}

步骤3：重新启动并验证

保存配置文件
重启克劳德桌面完全（退出并重新打开）
验证连接：寻找🔌 克劳德桌面中的图标，表示MCP服务器已连接
首次身份验证：首次使用时，浏览器窗口将打开，要求您：
- 登录您的Google帐户
- 授予Gmail读取和撰写访问权限
- 服务器将保存 token.json 文件在 credentials/ 目录

故障排除

服务器未连接？

验证路径是绝对的（而不是相对的，如 ~/ 或 ./)
检查Python虚拟环境是否已激活以及依赖项是否已安装
查看克劳德桌面日志： ~/Library/Logs/Claude/mcp*.log （macOS）

身份验证失败？

确保 credentials.json 在 credentials/ 目录
删除 credentials/token.json 并重试重新验证
验证Gmail API是否已在Google云控制台中启用
检查OAuth范围包括 gmail.readonly 和 gmail.compose

服务器启动时崩溃？

手动运行以查看错误： .venv/bin/python main.py
检查已安装的所有依赖项： uv sync

电子邮件写作指南（MCP资源）

此服务器将全面的电子邮件编写指南作为MCP资源公开。克劳德在起草电子邮件时可以访问这些信息，以确保专业、一致的沟通。

可用资源

固定URI上有三种资源：

file:///email-guidelines/7cs-communication.md -有效沟通的7C
- 专业电子邮件框架（清晰、简洁、正确、连贯、完整、礼貌、具体）
- 确保所有电子邮件符合专业标准
file:///email-guidelines/personal-templates.md -个人电子邮件模板
- 11个常见个人任务模板（约会、报价、生日祝福、邻居通信等）
- 适用于日常电子邮件场景的现成格式
file:///email-guidelines/ai-drafting-directive.md -AI电子邮件起草指令
- 包含戴尔·卡耐基、罗伯特·恰尔迪尼和斯蒂芬·柯维原则的综合指南
- 人物角色定义、按类别划分的语气映射、道德说服策略

资源如何工作

当MCP服务器连接时，Claude Desktop会自动将这些资源提供给Claude。克劳德可以：

自动访问 -通过MCP协议可以发现资源
需要时参考 -克劳德可以阅读资源来了解你的电子邮件写作标准
应用指南 -起草回复时使用7C框架和模板

使用资源

只需让克劳德起草电子邮件-资源会自动提供：

Draft a professional reply to this email about the budget review.

或者明确引用特定资源：

Draft a reply following the 7 Cs guidelines and use one of my personal templates if appropriate.

可选：谷歌文档集成

默认情况下，资源是从中的本地markdown文件读取的 docs/ 目录。您可以选择将服务器配置为从Google Docs中获取这些内容。

为什么要使用谷歌文档？

集中、可共享的指导方针
更新而不修改代码
与团队成员协作
版本历史

设置：

将您的三个指南文档上传到Google Docs
从URL获取文档ID： https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit

在中配置 src/gmail_mcp_server/configs/settings.toml:

[default.google_docs]
7cs_doc_id = "YOUR_7CS_DOCUMENT_ID"
templates_doc_id = "YOUR_TEMPLATES_DOCUMENT_ID"
directive_doc_id = "YOUR_DIRECTIVE_DOCUMENT_ID"

将Google Docs范围添加到settings.toml：

google_scopes = [
    "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
    "https://www.googleapis.com/auth/calendar.events.freebusy",
    "https://www.googleapis.com/auth/drive.readonly",
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.compose"
]

删除 credentials/token.json 并重新启动服务器以重新进行身份验证

退路： 如果Google Docs获取失败，服务器会自动回退到本地文件。

地方发展

设置

克隆存储库
安装依赖项： uv install
配置Gmail API凭据（请参阅 docs/gcp-setup.md)
运行服务器： uv run gmail-mcp-server

MCP检验员测试

调试和测试：

npx @modelcontextprotocol/inspector uv --directory /path/to/gmail-mcp run gmail-mcp-server

示例提示

提示1：阅读并总结未读电子邮件

Show me my 3 most recent unread emails and provide a brief summary of each one, including who sent it and what it's about.

提示2：带指南的回复草案

Check my unread emails. For the first one from Sarah, draft a professional reply using the 7 Cs guidelines.
I need to schedule a follow-up meeting to discuss Q4 budget and timeline.

提示3：使用个人电子邮件模板

I got an appointment reminder from my dentist for next Tuesday at 3pm.
Draft a confirmation reply using one of my personal email templates.

提示4：遵循所有准则的答复草案

Draft a reply to John's email using my AI drafting directive and the 7 Cs framework.
I need to apologize for the delayed report and explain it's now complete.

备注：起草后，在发送前检查您的Gmail草稿文件夹进行审核。

有关更多示例提示，请参见 docs/example-prompots.md

演示视频

观看Gmail MCP服务器的运行：

https://github.com/user-attachments/assets/demo_mcp.mov

演示显示：

从Gmail获取未读电子邮件
使用线程创建草稿回复

截图

Claude桌面中已连接MCP服务器

获取未读电子邮件

用7C框架起草专业回复

使用个人电子邮件模板

MCP行动提示

在Gmail中创建回复草稿

MCP提示

此服务器提供三个复杂的提示，这些提示利用了先进的提示工程技术：

1. `draft_professional_reply` -多级链+角色提示

目的： 使用思维链推理，根据7C框架和您的个人AI指令生成专业电子邮件回复。

论据：

thread_id （必填）：要回复的电子邮件线程ID
key_points （可选）：回复中应包含的要点
tone （可选）：期望的语气-正式、专业或友好（默认：专业）

快速工程技术： 思维链

从上下文检索到草稿创建的7步推理过程
从AI指令中应用一致的角色
根据7Cs检查表进行验证
英国英语格式

示例用法：

Use draft_professional_reply with thread_id="abc123", key_points="confirm meeting availability", tone="professional"

2. `schedule_meeting_reply` -上下文+日历集成

目的： 使用实时日历可用性上下文起草会议接受或提案。

论据：

thread_id （必填）：会议请求电子邮件线程ID
date_range_start （必填）：可用性检查的开始日期（ISO格式：YYYY-MM-DD）
date_range_end （必填）：可用性检查的结束日期（ISO格式：YYYY-MM-DD）
proposed_times （可选）：可选提出具体时间

快速工程技术： 情境提示

集成实时日历可用性数据
执行AI指令的“2个时隙”调度协议
带时区的英国日期/时间格式（BST/GMT）
基于会议请求的情境推理

示例用法：

Use schedule_meeting_reply with thread_id="xyz789", date_range_start="2025-12-16", date_range_end="2025-12-20"

3. `suggest_template` 小样本学习

目的： 分析一封电子邮件，并从11个模板中建议最合适的个人模板。

论据：

thread_id （必填）：要分析的电子邮件线程ID

快速工程技术： 小样本学习

与11个个人模板进行模式匹配
信心评分（0-100%）
解释模板选择的推理
显示所需的自定义字段
提供填充的模板预览

示例用法：

Use suggest_template with thread_id="def456"

资源使用矩阵

提示	7 Cs框架	电子邮件模板	AI指令	日历可用性
起草_专业_回复	✅ 是	✅ 是（可选）	✅ 是	❌ 没有
schedule_meeting_reply	✅ 是	❌ 否	✅ 是	✅ 是的
建议模板	❌ 否	✅ 是	❌ 否	❌ 没有

摘要：

所有提示至少访问2个资源
draft_professional_reply 使用3种资源（7Cs、AI指令、可选模板）
schedule_meeting_reply 使用3种资源（7C、AI指令、日历可用性）
suggest_template 使用1个主要资源（电子邮件模板）

项目状态：🧪 测试

所有核心要求和拓展目标都已成功实施和测试。

使用说明

📬️ Gmail MCP服务器

概述

核心功能

MCP能力

工具

资源

延伸目标

1.通过MCP资源建立专业写作框架

2.先进的MCP提示与快速工程

3.谷歌文档集成（可选）

4.谷歌日历集成（可选）

里程碑

核心要求

快速开始

先决条件

Gmail API设置

Claude桌面配置

步骤1：找到您的配置文件

步骤2：添加MCP服务器配置

步骤3：重新启动并验证

故障排除

电子邮件写作指南（MCP资源）

可用资源

资源如何工作

使用资源

可选：谷歌文档集成

地方发展

设置

MCP检验员测试

示例提示

提示1：阅读并总结未读电子邮件

提示2：带指南的回复草案

提示3：使用个人电子邮件模板

提示4：遵循所有准则的答复草案

演示视频

截图

Claude桌面中已连接MCP服务器

获取未读电子邮件

用7C框架起草专业回复

使用个人电子邮件模板

MCP行动提示

在Gmail中创建回复草稿

MCP提示

1. draft_professional_reply -多级链+角色提示

2. schedule_meeting_reply -上下文+日历集成

3. suggest_template 小样本学习

资源使用矩阵

项目状态：🧪 测试

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

Flomo笔记服务

AI开发助手

必应中文搜索MCP服务器

3D资产生成服务

1. `draft_professional_reply` -多级链+角色提示

2. `schedule_meeting_reply` -上下文+日历集成

3. `suggest_template` 小样本学习