Gmail-mcp-服务器

Name: Gmail-mcp-服务器
Author: Quantum-369

作者：Quantum-36915 星标更新：2025-07-08

安装使用来源：spider==github.com

项目介绍

Gmail MCP 服务器

一个使用 MCP（消息控制协议）框架构建的强大且灵活的 Gmail 集成服务器。此服务器提供了一个强大的接口来与 Gmail API 进行交互，提供了读取、发送和管理电子邮件的程序化功能。

功能

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

先决条件

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

Python 3.12 或更高版本
启用了 Gmail API 的 Google Cloud 项目
OAuth 2.0 客户端 ID 凭据
所需的 Python 包（在 pyproject.toml 中指定）

安装

通过 Smithery 安装

要通过 Smithery 自动安装 Gmail 集成服务器：

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

克隆仓库：

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

创建并激活虚拟环境：

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

安装依赖项：

pip install .

在 Ubuntu 上运行

安装 Python 3.12 并创建虚拟环境（如果尚未安装）：

sudo apt install python3.12 python3.12-venv -y
python3.12 -m venv venv
source venv/bin/activate

将下载的 client_secret.json 文件放置在项目根目录中。
为要使用的 Gmail 账户生成 OAuth 令牌。复制脚本打印的 URL 到浏览器中，并完成登录过程：
```
python gmail_token_creator.py
```
启动服务器：
```
python gmail_server.py
```

设置 Google Cloud 项目

前往 Google Cloud 控制台
创建新项目或选择现有项目
为您的项目启用 Gmail API
创建 OAuth 2.0 凭据：
- 前往“APIs & Services” > “Credentials”
- 点击“Create Credentials” > “OAuth client ID”
- 选择“Desktop app”作为应用类型
- 下载客户端配置文件
将下载的文件重命名为 client_secret.json 并放置在项目根目录中

配置

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

email_identifier = 'your.email@gmail.com'  # 对于每个账户更改此值

运行令牌创建器以验证您的 Gmail 账户：

python gmail_token_creator.py

脚本会打印一个授权 URL。将该 URL 复制到您的网络浏览器中，完成 Google 同意流程，并在提示时将验证码复制回终端。将在 token_files/ 目录中创建一个用于未来使用的令牌文件。

对于要集成的每个 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

使用 Docker 运行

您还可以使用提供的 Dockerfile 构建容器镜像：

docker build -t gmail-mcp-server .
docker run -v $(pwd)/client_secret.json:/app/client_secret.json \
           -v $(pwd)/token_files:/app/token_files gmail-mcp-server

容器运行相同的服务器，并将认证令牌存储在主机上的 token_files 目录中，以便它们在运行之间持久存在。

可用工具

发送邮件：

await send_gmail(
    email_identifier="your.email@gmail.com",
    to="recipient@example.com",
    subject="测试主题",
    body="邮件正文内容",
    attachment_paths=["附件路径"]
)

搜索邮件：

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

读取最新邮件：

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

下载附件：

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
启用文件和控制台日志记录
提供详细的错误消息用于调试

贡献

分叉仓库
创建功能分支
提交您的更改
推送到分支
创建拉取请求

许可证

Apache License 2.0

支持

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