Enhanced Gmail MCP Server

增强版 Gmail MCP 服务

一款功能强大、特性丰富的 Gmail 集成模型上下文协议（MCP）服务，使用 Python 编写。该服务可让 Claude 等 AI 助手通过自然语言与 Gmail 交互，提供全面的邮件管理功能。

🌟 主要功能

📧 完整的邮件管理

• 发送邮件，可自定义主题、内容和收件人
• 阅读和检索邮件内容及完整元数据
• 确认后将邮件移至垃圾箱
• 将邮件标记为已读或未读
• 直接在浏览器中打开邮件

📝 草稿管理

• 创建草稿邮件，供日后审核
• 列出所有草稿邮件
• 编辑现有草稿

🏷️ 高级标签管理

• 列出所有可用标签
• 创建自定义标签
• 为邮件添加或移除标签
• 重命名现有标签
• 删除未使用的标签
• 按标签搜索邮件

📁 文件夹整理

• 创建新文件夹（通过 Gmail 标签实现）
• 在文件夹之间移动邮件
• 列出所有可用文件夹

🔍 强大的搜索与筛选

• 使用 Gmail 的高级查询语法搜索邮件
• 创建、管理和删除邮件过滤器
• 按发件人、收件人、主题、内容等筛选
• 使用灵活的参数自定义搜索结果

🗄️ 归档管理

• 归档邮件（从收件箱移除，但不删除）
• 批量归档符合搜索条件的多封邮件
• 列出所有已归档邮件
• 将已归档邮件恢复到收件箱

🚀 开始使用

前提条件

• Python 3.12+
• Python MCP SDK >= 2.0
• 已启用 Gmail API 的 Google Cloud 项目
• OAuth 2.0 凭据

安装

# Clone the repository
git clone https://github.com/theposch/gmail-mcp.git
cd gmail-mcp

# Set up a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

Google Cloud 设置

1. 创建新的 Google Cloud 项目
2. 启用 Gmail API
3. 配置 OAuth 同意屏幕：
   • 选择“External”用户类型
   • 将你的邮箱添加为测试用户
   • 添加以下范围：https://www.googleapis.com/auth/gmail/modify
4. 创建 OAuth 2.0 凭据：
   • 选择“Desktop app”作为应用类型
   • 下载 JSON 凭据文件

配置

安全地存储凭据，并在运行服务时指定其位置：

# Example directory structure for credentials
mkdir -p ~/.gmail-mcp
# Move your downloaded credentials file
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

🔧 使用方法

在 Claude Desktop 中运行

将以下内容添加到 Claude Desktop 配置文件中（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/absolute/path/to/credentials.json",
        "--token-path",
        "/absolute/path/to/tokens.json"
      ]
    }
  }
}

使用 MCP Inspector 测试

测试和调试时，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector uv run /path/to/gmail-mcp/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json

🔐 安全注意事项

• 切勿将凭据或令牌文件提交到版本控制系统
• 将凭据存储在安全的位置，并设置适当的权限
• 执行敏感操作前，服务会请求用户确认
• 定期检查 Google Cloud Console 中是否存在异常活动
• 可考虑使用环境变量存储敏感路径

🛠️ 架构

此实现采用全面的单文件架构，通过 Google API 客户端库处理所有 Gmail 操作。主要组件包括：

• 支持自动令牌刷新的 OAuth2 身份验证
• 全面的错误处理和日志记录
• 具有清晰输入架构的结构化工具定义
• 高效的邮件解析与格式化

📚 示例提示词

连接 Gmail MCP 服务后，试试向 Claude 输入以下提示词：

• “显示我的未读邮件”
• “搜索来自 [email protected] 且带有附件的邮件”
• “创建一个名为‘Important Projects’的新标签”
• “起草一封关于即将举行的会议、发给 [email protected] 的邮件”
• “归档所有来自 [email protected] 的邮件”
• “创建一个过滤器，自动为来自我团队的邮件添加标签”

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

📄 许可证

本项目采用 GPL-3.0 License 授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 灵感来自社区中的各种 MCP 服务实现
• 基于 Model Context Protocol 框架构建
• 使用 Google 官方 API 客户端库