增强型Gmail MCP服务器

这是一个功能强大的模型上下文协议（MCP）服务器，用于与Gmail集成，使用Python编写。该服务器使像Claude这样的AI助手能够通过自然语言与Gmail进行交互，提供全面的电子邮件管理能力。

🌟 主要特性

📧 完整的电子邮件管理

• 发送带有自定义主题、内容和收件人的电子邮件
• 读取并检索带有完整元数据的电子邮件内容
• 确认后将电子邮件移至垃圾箱
• 将电子邮件标记为已读/未读
• 直接在浏览器中打开电子邮件

📝 草稿管理

• 创建供以后审阅的草稿邮件
• 列出所有草稿邮件
• 编辑现有草稿

🏷️ 高级标签管理

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

📁 文件夹组织

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

🔍 强大的搜索与过滤

• 使用Gmail的高级查询语法搜索电子邮件
• 创建、管理和删除电子邮件过滤器
• 根据发件人、收件人、主题、内容等进行过滤
• 使用灵活参数定制搜索结果

🗄️ 归档管理

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

🚀 快速开始

先决条件

• Python 3.8+
• 启用了Gmail API的Google Cloud项目
• OAuth 2.0凭证

安装

# 克隆仓库
git clone https://github.com/theposch/gmail-mcp.git
cd gmail-mcp

# 设置虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate

# 安装包
pip install -e .

Google Cloud设置

1. 创建一个新的Google Cloud项目
2. 启用Gmail API
3. 配置OAuth同意屏幕：
   • 选择“外部”用户类型
   • 添加您的电子邮件作为测试用户
   • 添加范围：https://www.googleapis.com/auth/gmail/modify
4. 创建OAuth 2.0凭证：
   • 选择“桌面应用”作为应用程序类型

• 下载JSON凭证文件

配置

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

# 示例凭证目录结构
mkdir -p ~/.gmail-mcp
# 移动您下载的凭证文件
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",
        "/绝对路径/to/gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/绝对路径/to/credentials.json",
        "--token-path",
        "/绝对路径/to/tokens.json"
      ]
    }
  }
}

使用MCP Inspector进行测试

对于测试和调试，请使用MCP Inspector：

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

🔐 安全注意事项

• 切勿将凭证或令牌文件提交到版本控制
• 将凭证存储在具有适当权限的安全位置
• 服务器将在执行敏感操作前请求用户确认
• 定期审查Google Cloud Console中的异常活动
• 考虑使用环境变量来存储敏感路径

🛠️ 架构

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

• 自动刷新令牌的OAuth2认证
• 全面的错误处理和日志记录
• 结构化的工具定义，具有清晰的输入模式
• 高效的电子邮件解析和格式化

📚 示例提示

连接Gmail MCP服务器后，尝试这些提示与Claude：

• “显示我的未读邮件”
• “搜索来自example@domain.com且带有附件的邮件”
• “创建名为‘重要项目’的新标签”
• “起草一封关于即将举行的会议的邮件给john@example.com”
• “归档所有来自newsletter@example.com的邮件”
• “创建一个过滤器以自动对来自我的团队的邮件进行标签”

🤝 贡献

欢迎贡献！请随意提交拉取请求。

1. 分叉仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加一些精彩的功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开拉取请求

📄 许可证

本项目根据GPL-3.0许可证发布 - 查看LICENSE文件了解详情。

🙏 致谢

• 受社区中各种MCP服务器实现的启发
• 使用模型上下文协议框架构建
• 使用Google官方API客户端库