AI导哈

Gmail邮件管理服务器

一个实现Gmail API集成的Python服务器，提供读取未读邮件和创建草稿回复功能，用于AI助手与Gmail账户的交互。

  • by Pinkish-Warrior
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Pinkish-Warrior/gmail-mcp-server

使用说明

Gmail模型上下文协议（MCP）服务器

该项目在Python中实现了一个模型上下文协议（MCP）服务器，使AI助手（如Claude Desktop）能够与用户的Gmail帐户进行交互。该服务器公开了两个主要工具：一个用于读取未读电子邮件，另一个用于创建草稿回复，为人工智能提供端到端的电子邮件管理工作流程。

特性

  • get_unread_emails：检索未读电子邮件列表，提供发件人、主题、片段和回复所需的线程ID。
  • create_draft_reply：在现有电子邮件线程中创建草稿回复，通过设置 ThreadId 以及适当的电子邮件标题(In-Reply-To, References).
  • 安全认证：将官方的Google API Python客户端与OAuth 2.0一起用于桌面应用程序，将凭据安全地存储在本地 token.json 初始授权后的文件。

先决条件

要运行此服务器，您需要：

1.Python 3.10+ 2. 启用Gmail的Google帐户。 3. 谷歌云项目 随着 Gmail API 启用。 4. OAuth 2.0客户端ID 为了一个 桌面应用程序 从谷歌云控制台。

安装指南

1.克隆存储库并安装依赖项

git clone <YOUR_REPO_URL>
cd gmail_mcp_server
python --version  # Should be 3.10+
pip install -r requirements.txt

2.配置Gmail API凭据

  1. 去 谷歌云控制台.

  2. 确保选择了正确的项目 Gmail API 已启用。

  3. 引导到 API和服务 > 凭证.

  4. 点击 +创建凭据 > OAuth客户端ID.

  5. 选择 应用程序类型 作为 桌面应用程序.

  6. 为其命名（例如，“Gmail MCP服务器”）。

  7. 点击 创建 然后 下载JSON.

  8. 将下载的文件重命名为 credentials.json 并将其放置在此项目的根目录中(gmail_mcp_server/).

  9. 验证凭据文件：

    ls -la credentials.json
# Should show the file with your OAuth credentials

3.运行服务器并授权访问

第一次运行服务器时，它将启动OAuth 2.0流来授权访问您的Gmail帐户。

python gmail_server.py
# Expected output:
# INFO - gmail-mcp-server - Initializing new Gmail service
# [Browser opens for authorization]
# INFO - gmail-mcp-server - Gmail service initialized successfully
  1. 浏览器窗口将打开，提示您登录您的Google帐户并授予必要的权限(gmail.readonly 和 gmail.compose).
  2. 成功授权后，a token.json 文件将在项目目录中创建。此文件安全地存储您的访问和刷新令牌，允许服务器在没有重新授权的情况下运行，直到令牌过期或被撤销。

4.配置克劳德桌面

  1. 确保MCP服务器正在您的终端中运行。
  2. 找到您的Claude Desktop配置文件。
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • 视窗: %APPDATA%\Claude\claude_desktop_config.json
  3. 将以下条目添加到 mcpServers 部分，替换 /path/to/your/project 与你的绝对路径 gmail_server.py 文件：
{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["/path/to/your/project/gmail_mcp_server/gmail_server.py"]
    }
  }
}
  1. 验证JSON语法
# macOS/Linux
cat ~/Library/Application\ Support/Claude  claude_desktop_config.json | python -m json.tool
# Should output formatted JSON without errors
  1. 重新启动克劳德桌面。AI助手现在可以访问 Gmail 服务器及其工具。

Claude Desktop使用示例

配置后，您可以使用以下提示：

提示 预期的AI操作
“我有未读的电子邮件吗？如果有，请列出前三封的发件人和主题。” 通话 get_unread_emails 并对结果进行了总结。
“为[发件人姓名]的电子邮件起草一份回复，主题为[主题]，说‘谢谢你的来信。我会在今天结束前给你回复。’” 电话 get_unread_emails 找到线程ID，然后调用 create_draft_reply 使用ID和指定的正文。

演示截图

1.克劳德桌面配置

在Claude Desktop的设置中配置的MCP服务器。

2.收到未读电子邮件

Claude Desktop使用 get_unread_emails 工具。

3.创建回复草稿

用户请求克劳德为电子邮件创建回复草稿。

Claude使用以下命令成功创建了回复草稿 create_draft_reply 工具。

4.Gmail草稿文件夹

创建的草稿回复出现在Gmail的草稿文件夹中。

验证您的设置

1.独立测试服务器

在连接到Claude Desktop之前，请验证服务器是否正常工作：

python gmail_server.py

您应该看到：

  • OAuth浏览器窗口打开（仅限首次运行）
  • 无错误消息
  • 服务器运行时不会崩溃

按Ctrl+C停止。

2.使用Claude Desktop进行测试

配置完Claude Desktop后（见上述步骤4）：

  1. 重新启动克劳德桌面
  2. 打开新对话
  3. 寻找🔌 指示已连接服务器的MCP图标
  4. 尝试以下测试提示：
  • “我有未读的电子邮件吗？”
    • “我第一封未读电子邮件的主题是什么？”
    • “起草一份回复[发件人姓名]说谢谢”

3.检查日志

如果出现问题，请检查日志：

  • 服务器日志：手动运行服务器以查看输出
  • 克劳德桌面日志:
    • macOS： ~/Library/Logs/Claude/mcp*.log
    • 窗户： %APPDATA%\Claude\Logs\mcp*.log

故障排除

常见问题

  • “未找到credentials.json”

  • 确保您已从谷歌云控制台下载OAuth凭据

  • 将文件精确重命名为 credentials.json （不是 credentials (1).json)

  • 将其放置在项目根目录中

“授予无效”或“令牌已过期或吊销”

  • 删除 token.json 并再次运行服务器以重新授权
  • 检查您的OAuth同意屏幕是否配置正确

“错误403：拒绝访问”

  • 确保在Google云控制台中启用Gmail API
  • 验证OAuth同意屏幕是否包含您作为测试用户的Gmail帐户

“超出费率限制”

  • Gmail API有配额（250个配额单位/用户/秒）
  • 请稍候几分钟，然后重试
  • 考虑减少 max_results 参数

服务器未出现在Claude Desktop中

  • 检查 claude_desktop_config.json 语法（有效的JSON）
  • 验证到的绝对路径 gmail_server.py 是正确的
  • 配置更改后重新启动Claude Desktop
  • 检查克劳德桌面日志： ~/Library/Logs/Claude/mcp*.log （macOS）

常见问题

Q： 我可以在Google Workspace（G Suite）帐户上使用此功能吗？ A： 是的，但您可能需要域管理员批准才能启用Gmail API。

Q： 我的电子邮件数据安全吗？ A： 是的。所有身份验证都使用OAuth 2.0，凭据存储在本地，数据永远不会离开您的计算机。AI助手仅在您明确要求时才访问电子邮件。

Q： 人工智能可以自动发送电子邮件吗？ A： 否。此服务器仅创建 草稿，未发送电子邮件。您必须从Gmail手动审阅和发送草稿。

Q： 需要哪些Gmail范围？ A. gmail.readonly （阅读电子邮件）和 gmail.compose （创建草稿）。这些是最低权限。

Q： 如何撤销访问权限？ A： 删除 token.json 并前往 谷歌 撤销应用程序访问权限。

Q： 我可以使用多个Gmail帐户吗？ A： 不是同时。要切换帐户，请删除 token.json 并重新授权。

Q： 这适用于其他电子邮件提供商吗？ A： 不，只有Gmail。其他提供商将需要不同的API集成。

Q： Gmail API的费率限制是多少？ A： 每用户每秒250个配额单位，每天10亿个。每次读取/列表操作花费5个单位。典型用法不会达到极限。

扩展目标：利用外部环境增强回复

要实现伸展目标，您可以修改 create_draft_reply 函数首先从外部源（例如，样式指南的本地Markdown文件或模板的简单API）检索上下文，然后将该上下文作为提示的一部分或作为附加资源传递给LLM。

例如，您可以添加一个本地文件 style_guide.md 并在调用LLM生成回复体之前读取其内容。

# Example of reading a local style guide
with open("style_guide.md", "r") as f:
    style_guide = f.read()

# You would then pass this to the LLM to influence the reply_body generation
# (This part is handled by the LLM client, not the MCP server itself)

相关 MCP