AI导哈

Gmail邮件处理服务器

一个基于MCP协议的服务器，允许AI助手读取未读Gmail邮件并创建草稿回复。

  • by CharlesAD
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 CharlesAD/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 <your-repo-url> 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

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

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

  3. 创建OAuth凭据

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

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

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

    source .venv/bin/activate
python debug_gmail.py

    这将：

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

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

    确保你的 .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/<you>/Code/gmail-mcp-server/.venv/bin/python",
      "args": [
        "/Users/<you>/Code/gmail-mcp-server/server.py"
      ],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/Users/<you>/Code/gmail-mcp-server/credentials.json"
      }
    }
  }
}

替换 /Users/<you>/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: <PASTE_THREAD_ID> 以及一个回复正文，礼貌地确认我收到了他们的电子邮件，并建议下周打电话。告诉我什么 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客户端之外的任何第三方服务。

相关 MCP