Gmail MCP 服务器

一个提供 Gmail 集成能力的 MCP（模型上下文协议）服务器，供像 Claude Desktop 这样的 MCP 客户端使用。

特性

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

设置

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 的邮件？

安全

此服务器需要 OAuth2 身份验证与 Gmail：

• 您会在首次使用时在浏览器中被提示授权访问
• 凭证会本地保存到指定的令牌文件中
• 可以随时通过您的 Google 帐户设置 revoke 授权
• 仅请求对 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

开发

该服务器使用 Model Context Protocol 提供：

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

日志记录

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

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

贡献

欢迎提交拉取请求！请确保：

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