Gmail MCP 服务器

一个强大且灵活的 Gmail 集成服务器，使用 MCP (消息控制协议) 框架构建。该服务器提供了一个强大的接口来与 Gmail API 交互，提供以编程方式读取、发送和管理电子邮件的功能。

功能

• 从多个 Gmail 帐户读取电子邮件
• 发送带有附件的电子邮件
• 使用高级查询选项搜索电子邮件
• 下载电子邮件附件
• 处理电子邮件对话和线程
• 实时电子邮件监控
• 支持多个 Gmail 帐户

前提条件

在运行 Gmail MCP 服务器之前，请确保您拥有以下内容：

1. Python 3.12 或更高版本
2. 启用了 Gmail API 的 Google Cloud 项目
3. OAuth 2.0 客户端 ID 凭据
4. 必需的 Python 包 (在 pyproject.toml 中指定)

安装

通过 Smithery 安装

要通过 Smithery 自动安装用于 Claude Desktop 的 Gmail 集成服务器：

npx -y @smithery/cli install @Quantum-369/Gmail-mcp-server --client claude

1. 克隆存储库：

git clone <your-repository-url>
cd gmail-mcp-server

2. 创建并激活虚拟环境：

python -m venv venv
# 在 Windows 上
venv\Scripts\activate
# 在 Unix/MacOS 上
source venv/bin/activate

3. 安装依赖项：

pip install .

设置 Google Cloud 项目

1. 转到 Google Cloud Console
2. 创建一个新项目或选择一个现有项目
3. 为您的项目启用 Gmail API
4. 创建 OAuth 2.0 凭据：
   • 转到 "API 和服务" > "凭据"
   • 点击 "创建凭据" > "OAuth 客户端 ID"
   • 选择 "桌面应用" 作为应用程序类型
   • 下载客户端配置文件
5. 将下载的文件重命名为 client_secret.json 并将其放置在项目根目录中

配置

1. 在 gmail_token_creator.py 中设置电子邮件标识符：

email_identifier = 'your.email@gmail.com'  # 为每个帐户更改此项

2. 运行令牌创建器以验证您的 Gmail 帐户：

python gmail_token_creator.py

3. 为要集成的每个 Gmail 帐户重复此过程

服务器结构

• gmail_server.py: 主要 MCP 服务器实现
• gmail_api.py: Gmail API 交互函数
• google_apis.py: Google API 身份验证实用程序
• 支持文件：
  • read_emails.py: 电子邮件读取功能
  • search_emails.py: 电子邮件搜索功能
  • send_emails.py: 电子邮件发送功能

用法

启动服务器

python gmail_server.py

可用工具

1. 发送电子邮件：

await send_gmail(
    email_identifier="your.email@gmail.com",
    to="recipient@example.com",
    subject="Test Subject",
    body="Email body content",
    attachment_paths=["path/to/attachment"]
)

2. 搜索电子邮件：

await search_email_tool(
    email_identifier="your.email@gmail.com",
    query="from:someone@example.com",
    max_results=30,
    include_conversations=True
)

3. 读取最新电子邮件：

await read_latest_emails(
    email_identifier="your.email@gmail.com",
    max_results=5,
    download_attachments=False
)

4. 下载附件：

await download_email_attachments(
    email_identifier="your.email@gmail.com",
    msg_id="message_id",
    download_all_in_thread=False
)

安全注意事项

• 安全地存储 client_secret.json，切勿将其提交到版本控制
• 保持令牌文件安全并将其添加到 .gitignore
• 使用环境变量存储敏感信息
• 定期轮换 OAuth 凭据
• 监控 API 使用情况并设置适当的配额

错误处理

该服务器包括全面的错误处理和日志记录：

• 日志写入 gmail_mcp.log
• 启用文件和控制台日志记录
• 用于调试的详细错误消息

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到分支
5. 创建一个 Pull Request

许可证

Apachelicense2.0

支持

对于问题和功能请求，请使用 GitHub 问题跟踪器。