Berkeley Gmail MCP

Gmail MCP服务器——加州大学伯克利分校

让克劳德直接访问您的伯克利Gmail（@Berkeley.edu），这样您就可以在不离开人工智能助手的情况下阅读、起草、发送和管理电子邮件。

注： 克劳德在发送或删除电子邮件之前，总是会要求您确认。

______________________________________________________________________

它能做什么？

• 阅读 您未读的电子邮件
• 起草并发送 电子邮件（可选HTML格式和文件附件）
• 垃圾 电子邮件
• 马克 电子邮件已读
• 打开 直接在浏览器中发送任何电子邮件

______________________________________________________________________

先决条件

在开始之前，请确保您已经：

• Python 3.12或更高版本 安装
• macOS、Linux或Windows与WSL
• A. 伯克利电子邮件帐户 （@berkeley.edu）
• 克劳德桌面版 安装
• 访问 伯克利谷歌云端硬盘 （用于凭证）

______________________________________________________________________

设置

1.克隆仓库

git clone https://github.com/kope-kope/berkeley-gmail-mcp.git
cd berkeley-gmail-mcp

2.下载凭据文件

下载 client_creds.json 从 Google 云端硬盘 并将其保存在项目根目录中。

您必须登录到您的 @berkeley.edu 帐户访问此文件。

3.配置您的显示名称

复制示例配置并填写您的姓名：

cp config.example.json config.json

编辑 config.json:

{
  "display_name": "Your Name"
}

这将设置中显示的显示名称 自 您发送的电子邮件字段。这是可选的——如果你跳过它，电子邮件将从你的原始电子邮件地址发出。

永不承诺 config.json 或您的凭据文件。 它们在这个回购中是合法的。

4.创建令牌文件占位符

touch app_tokens.json

此文件将在首次身份验证期间自动填充。

5.安装uv

紫外线 是运行服务器的推荐方式：

curl -LsSf https://astral.sh/uv/install.sh | sh

6.连接到克劳德桌面

将以下内容添加到您的Claude Desktop配置中 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/berkeley-gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/absolute/path/to/berkeley-gmail-mcp/client_creds.json",
        "--token-path",
        "/absolute/path/to/berkeley-gmail-mcp/app_tokens.json",
        "--config-path",
        "/absolute/path/to/berkeley-gmail-mcp/config.json"
      ]
    }
  }
}

替换 /absolute/path/to/berkeley-gmail-mcp 使用机器上的实际绝对路径。例如：

7.身份验证

Claude第一次启动服务器时，会打开一个浏览器窗口，要求您登录。 用你的 @berkeley.edu 账户 之后，您的令牌将保存在本地并自动重复使用。

______________________________________________________________________

用法

一旦通过身份验证，您就可以通过Claude Desktop与您的Gmail进行交互。以下是一些示例提示：

• “显示我的未读电子邮件”
• “起草一封电子邮件至professor@berkeley.edu关于办公时间”
• “发送我们刚刚起草的电子邮件”
• “在浏览器中打开昨天的电子邮件”
• “将该垃圾邮件移至垃圾箱”

注： 克劳德在发送或删除电子邮件之前总是会要求确认。

高级功能

• HTML电子邮件：起草时，您可以要求Claude将电子邮件格式化为HTML格式
• 附件：您可以指定要附加到电子邮件的文件路径
• 多个收件人：您可以同时向多人发送电子邮件

______________________________________________________________________

故障排除

常见问题

服务器无法启动

• 错误：“没有名为'gmail'的模块” → Run uv sync 在项目目录中安装依赖项
• 错误：“找不到文件：client_creds.json” → 确保您已下载该文件，并且它位于项目根目录中
• 错误：“权限被拒绝” → 检查项目目录上的文件权限

身份验证问题

• 浏览器无法打开 → 手动访问终端中显示的URL
• “访问被阻止” → 确保您使用您的@berkeley.edu帐户登录
• 令牌已过期 → 删除 app_tokens.json 并重新验证

电子邮件操作

• “没有未读邮件”，但你有一些 → 检查它们是否在您的收件箱中（未存档）
• 附件未发送 → 验证文件路径是否为绝对路径以及文件是否存在
• 电子邮件未出现在已发送文件夹中 → 检查“消息发送成功”确认和消息ID

使用MCP检查器进行调试

使用 MCP检查员 直接测试服务器：

npx @modelcontextprotocol/inspector uv run /absolute/path/to/berkeley-gmail-mcp/src/gmail/server.py \
  --creds-file-path /absolute/path/to/berkeley-gmail-mcp/client_creds.json \
  --token-path /absolute/path/to/berkeley-gmail-mcp/app_tokens.json \
  --config-path /absolute/path/to/berkeley-gmail-mcp/config.json

______________________________________________________________________

安全

最佳实践

• 永不承诺 client_creds.json, app_tokens.json，或 config.json 到版本控制（它们被忽略）
• 存储凭据文件 安全地限制权限(chmod 600 *.json 在项目目录中）
• 检查代码 在运行之前，此服务器已修改您的Gmail访问权限
• 保护令牌文件 就像密码一样，它们包含OAuth凭据
• 撤销访问权限 在你的 Google帐户设置 如果您怀疑凭据已泄露

访问哪些数据？

此服务器请求 gmail.modify 范围，允许：

• 读取电子邮件元数据和内容
• 代表您发送电子邮件
• 将电子邮件移至垃圾箱
• 将电子邮件标记为已读

服务器 不 永久删除电子邮件或访问垃圾箱中的电子邮件。

______________________________________________________________________

发展

在当地发展

1. 克隆存储库并导航到项目目录
2. 安装依赖项（包括开发依赖项）：

   uv sync --extra dev

1. 直接运行服务器：

   uv run python src/gmail/server.py \
     --creds-file-path /path/to/client_creds.json \
     --token-path /path/to/app_tokens.json \
     --config-path /path/to/config.json

项目结构

berkeley-gmail-mcp/
├── src/gmail/
│   ├── __init__.py      # Entry point and CLI argument parsing
│   └── server.py        # Core MCP server and Gmail API integration
├── config.example.json  # Example configuration
├── config.json          # Your config (gitignored)
├── client_creds.json    # OAuth credentials (gitignored)
├── app_tokens.json      # Auth tokens (gitignored, auto-generated)
├── pyproject.toml       # Project dependencies and metadata
├── LICENSE              # GPL-3.0 license
└── README.md            # This file

代码风格

本项目使用：

• 黑色 用于代码格式化（行长：100）
• 米皮 用于类型检查
• 拉夫 对于linting
• pytest 用于测试

运行格式化和检查：

uv run black src/
uv run mypy src/
uv run ruff check src/

贡献

看 贡献.md 了解如何为这个项目做出贡献的指导方针。

______________________________________________________________________

常见问题解答

Q： 多个人可以使用同一个吗 client_creds.json 文件？ A： 是的！这 client_creds.json 文件是Berkeley Gmail应用程序的OAuth客户端凭据。多个用户可以共享此文件。每个用户将生成自己的 app_tokens.json 当他们进行身份验证时。

Q： 我可以使用非伯克利Gmail帐户吗？ A： 不提供 client_creds.json 文件，因为它是专门为@berkeley.edu帐户配置的。但是，您可以在Google Cloud Console中为其他帐户创建自己的OAuth凭据。

Q： 此服务器请求什么Gmail范围？ A： 服务器请求 gmail.modify，它允许阅读、发送电子邮件和将电子邮件移动到垃圾桶。确实如此 不 请求 gmail.readonly 或 gmail.compose --它需要修改访问权限，将电子邮件标记为已读并将其丢弃。

Q： 这在手机上有效吗？ A： 不，这是Claude Desktop的服务器，它是一个桌面应用程序。但是，通过服务器发送的电子邮件将显示在所有设备上的Gmail中。

Q： 如何撤销访问权限？ A： 访问您的 Google帐户权限页面，找到“Berkeley Gmail MCP”，然后单击“删除访问权限”。然后删除您的 app_tokens.json 文件。

Q： 为什么用uv代替pip？ A. 紫外线 比pip（10-100x）快得多，自动创建隔离环境，并通过以下方式提供可重复的构建 uv.lock。它还简化了部署 uv run.

______________________________________________________________________

许可证

此项目根据GNU通用公共许可证v3.0或更高版本获得许可。看 许可证 了解详情。