Gmail MCP 服务器

一个 MCP (模型上下文协议) 服务器，为 MCP 客户端（如 Claude Desktop）提供 Gmail 集成功能。

功能

• 查看 Gmail 收件箱中的最新邮件
• 使用 Gmail 的搜索语法搜索邮件
• 使用 Gmail API 进行安全的 OAuth2 身份验证

设置

1. Google Cloud 项目设置

1. 在 https://console.cloud.google.com/ 创建一个 Google Cloud 项目
2. 启用 Gmail API
3. 创建 OAuth 2.0 凭据：
   • 应用程序类型：桌面应用程序
   • 将凭据下载为 credentials.json

2. 安装

# 创建一个 conda 环境
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail

# 安装包
cd gmail-mcp-server
pip install -e .

3. Claude Desktop 配置

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

将 /path/to/ 替换为你的实际路径。 令牌文件将在你首次进行身份验证时自动创建。

4. 首次运行

当你第一次尝试通过 Claude 访问 Gmail 时，系统会提示你在浏览器中授权该应用程序。 授权后，你的凭据将保存到令牌文件中以供将来使用。

可用资源

• gmail://inbox/recent - 返回你最近的 10 封邮件

可用工具

• search_emails
  • 描述：使用查询搜索 Gmail 邮件
  • 参数：
    • query (必需): Gmail 搜索查询（使用 Gmail 的标准搜索语法）
    • max_results (可选): 要返回的最大结果数（默认值：10）

搜索示例：

你能给我展示过去两天来自 sanrio 的任何邮件吗？

安全

此服务器需要使用 Gmail 进行 OAuth2 身份验证：

• 首次使用时，系统会提示你在浏览器中授权访问
• 凭据本地存储在指定的令牌文件中
• 可以随时通过你的 Google 帐户设置撤销访问权限
• 仅请求对 Gmail 的读取访问权限（无写入权限）

环境变量

• GMAIL_CREDENTIALS_FILE (必需): 你的 Google OAuth 凭据文件的路径
• GMAIL_TOKEN_FILE (必需): 将保存身份验证令牌的路径

对于测试，你可以直接运行服务器：

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

开发

该服务器使用模型上下文协议来提供：

• 对最近邮件的资源访问
• 对邮件搜索的工具支持
• 安全的 OAuth2 身份验证流程
• 自动令牌刷新

日志记录

服务器将有关其操作的详细信息记录到 stderr，包括：

• 服务器启动信息
• 身份验证状态
• 资源和工具使用情况
• 任何错误或问题

贡献

欢迎提交 Pull Request！ 请确保：

• 更新任何新功能的文档
• 添加适当的错误处理
• 使用新功能测试 OAuth 流程
• 遵循现有的代码风格