Ajbr0wn Gmail MCP Server

🚀 Gmail MCP 服务器

Gmail MCP 服务器是一个提供 Gmail 集成能力的 MCP（模型上下文协议）服务器，可供像 Claude Desktop 这样的 MCP 客户端使用，能让用户便捷地在客户端中访问 Gmail 相关功能。

🚀 快速开始

要使用 Gmail MCP 服务器，您需要按照以下步骤进行设置：

1. Google Cloud 项目设置：
   • 在 Google Cloud 控制台 创建一个 Google Cloud 项目。
   • 启用 Gmail API。
   • 创建 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 收件箱中的 10 封最新邮件。
• 邮件搜索功能：支持使用 Gmail 的搜索语法搜索邮件。
• 安全身份验证：基于 OAuth2 进行安全身份验证，与 Gmail API 集成。

📦 安装指南

Google Cloud 项目设置

1. 在 Google Cloud 控制台 创建一个 Google Cloud 项目。
2. 启用 Gmail API。
3. 创建 OAuth 2.0 凭证，应用类型选择桌面应用，并将凭证下载为 credentials.json。

安装依赖

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

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

配置 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/ 替换为实际路径，首次认证时会自动创建令牌文件。

💻 使用示例

可用资源

• 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，包括：

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

🔧 技术细节

该服务器基于 Model Context Protocol 构建，通过 OAuth2 与 Gmail API 进行安全集成。在首次运行时，会引导用户进行授权，并将凭证保存到本地令牌文件中。服务器提供了对最近邮件的资源访问和邮件搜索工具，支持使用 Gmail 的标准搜索语法。同时，服务器会自动刷新令牌，确保身份验证的有效性。在运行过程中，会将详细的操作信息记录到 stderr，方便开发人员进行调试和监控。

📄 许可证

文档中未提及许可证相关信息。

贡献

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

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