Gmail MCP Server Claude

Gmail MCP服务器

MCP（模型上下文协议）服务器，允许AI助手：

• 通过Gmail API阅读未读Gmail邮件
• 创建正确的线程 答复草稿 在Gmail中

作为端到端的示例，为Anthropic计划基础项目而构建。

______________________________________________________________________

特性

get_unread_emails(maxResults: int = 10)

从收件箱中获取未读电子邮件并返回JSON结构：

{
  "emails": [
    {
      "id": "string",
      "threadId": "string",
      "from": "string",
      "subject": "string",
      "snippet": "string",
      "internalDate": "string"
    }
  ]
}

领域：

• id –Gmail邮件ID
• threadId –Gmail线程ID（回复时使用）
• from –发件人
• subject –电子邮件主题
• snippet –消息的简短预览
• internalDate –消息时间戳（自纪元以来的毫秒，以字符串形式）

create_draft_reply(threadId: str, replyBody: str)

创建一个 答复草稿 在指定的Gmail线程中。

返回JSON结构：

{
  "draftId": "string | null",
  "threadId": "string",
  "to": "string",
  "subject": "string"
}

• 正确地使用 In-Reply-To 和 References 标题。
• 将草稿保留在您的Gmail草稿文件夹中，以便手动审阅/发送。

OAuth令牌存储在本地 token.json 并自动刷新。

______________________________________________________________________

架构/技术栈

• 语言： Python 3
• MCP服务器： mcp Python SDK（FastMCP）
• Gmail API客户端： google-api-python-client, google-auth-oauthlib
• 客户： Claude Desktop通过stdio使用MCP

______________________________________________________________________

先决条件

• 已安装Python 3.10+
• 已安装Claude Desktop
• 可以访问Gmail的Google帐户
• 启用Gmail API的谷歌云项目

______________________________________________________________________

设置

1. 克隆存储库并创建虚拟环境

   git clone  gmail-mcp-server
   cd gmail-mcp-server

   python3 -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1

   pip install -r requirements.txt

1. 创建谷歌云项目并启用Gmail API

- 转到Google Cloud控制台。 - 创建（或选择）一个项目。 - 启用 Gmail API 对于这个项目。 - 配置OAuth同意屏幕（外部/测试适合个人使用）。

1. 创建OAuth凭据

- 在 API和服务→ 凭证，创建一个 OAuth客户端ID. - 应用程序类型： 桌面应用. - 下载JSON文件并将其保存在项目根目录中：

   credentials.json

1. 首次Gmail身份验证（可选健全性检查）

该项目包括一个小脚本，用于验证Gmail是否配置正确：

   source .venv/bin/activate
   python debug_gmail.py

这将：

- 打开浏览器窗口，要求您登录并批准Gmail范围。 - 保存本地 token.json 文件以备将来运行。 - 打印未读邮件的ID。

1. 忽略本地机密和特定于环境的文件

确保你的 .gitignore （在本回购中）至少包括：

   .venv/
   __pycache__/
   credentials.json
   token.json
   *.log

这些文件必须 从不 致力于GitHub。

______________________________________________________________________

Claude桌面配置

Claude Desktop使用 claude_desktop_config.json 了解如何启动MCP服务器。

在macOS上，此文件通常位于：

~/Library/Application Support/Claude/claude_desktop_config.json

添加（或合并）以下配置：

{
  "mcpServers": {
    "gmail-mcp-server": {
      "command": "/Users//Code/gmail-mcp-server/.venv/bin/python",
      "args": [
        "/Users//Code/gmail-mcp-server/server.py"
      ],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/Users//Code/gmail-mcp-server/credentials.json"
      }
    }
  }
}

替换 /Users//Code/gmail-mcp-server 在您的计算机上显示此项目的实际路径。

在编辑文件之后， 退出并重新启动Claude Desktop 因此，它选择了新的MCP服务器。

______________________________________________________________________

Claude中的用法

重新启动Claude Desktop后，打开一个新的聊天室并尝试：

列出并总结未读电子邮件

“使用 gmail-mcp-server 调用工具 get_unread_emails 随着 maxResults 5，然后总结电子邮件。”

克劳德将：

• 打电话给 get_unread_emails 工具。
• 接收未读电子邮件的JSON列表。
• 用自然语言总结它们。

检查原始JSON（用于调试/演示）

“呼叫 get_unread_emails 随着 maxResults 3并向我显示原始JSON输出。”

创建答复草稿

1. 首先获取未读电子邮件并检查JSON以找到 threadId.
2. 然后：

“使用 gmail-mcp-server 调用工具 create_draft_reply 由此 threadId: `

以及一个回复正文，礼貌地确认我收到了他们的电子邮件，并建议下周打电话。告诉我什么 draftId` 创建。”

1. 打开Gmail→ 草稿 在正确的线程中查看新创建的回复。

______________________________________________________________________

截图（用于项目提交）

建议在您的提交/仓库中包含以下截图：

• 克劳德来电 get_unread_emails 并显示JSON结果。
• 克劳德总结了未读的电子邮件。
• 克劳德来电 create_draft_reply 并报告创建的 draftId.
• Gmail UI以正确的线程显示草稿回复。

把它们放在一个 screenshots/ 文件夹，并根据需要在应用程序中引用它们。

______________________________________________________________________

安全说明

• 此服务器用于 本地、个人使用 作为一个学习/演示项目。
• credentials.json 和 token.json 是敏感的，必须保持本地化。
• 范围仅限于：

- gmail.readonly –阅读消息 - gmail.compose –创建草稿

• 服务器会 不 将凭据或电子邮件内容发送到除Gmail和本地Claude Desktop客户端之外的任何第三方服务。