增强型 Gmail MCP 服务器

一个功能强大且丰富的模型上下文协议 (MCP) 服务器，用于集成 Gmail，采用 Python 编写。该服务器使 Claude 等 AI 助手能够通过自然语言与 Gmail 交互，提供全面的电子邮件管理功能。

🌟 主要特点

📧 完整的电子邮件管理

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

📝 草稿管理

创建电子邮件草稿以供日后审阅
列出所有电子邮件草稿
编辑现有草稿

🏷️ 高级标签管理

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

📁 文件夹组织

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

🔍 强大的搜索和过滤功能

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

🗄️ 档案管理

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

🚀 入门

先决条件

Python 3.8+
启用 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 设置

创建新的 Google Cloud 项目
启用 Gmail API
配置OAuth 同意屏幕：
- 选择“外部”用户类型
- 将您的电子邮件添加为测试用户
- 添加范围： https://www.googleapis.com/auth/gmail/modify
创建OAuth 2.0 凭证：
- 选择“桌面应用”作为应用程序类型
- 下载 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 进行以下提示：

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

🤝 贡献

欢迎贡献代码！欢迎提交 Pull 请求。

分叉存储库
创建你的功能分支（ git checkout -b feature/amazing-feature ）
提交您的更改（ git commit -m 'Add some amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

📄 许可证

该项目根据 GPL-3.0 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

🙏 致谢

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

Enhanced Gmail MCP Server

Integrations