内容
# 克劳德-2-邮件
用于Gmail和谷歌日历的本地MCP服务器。 让您的AI代理读取/发送电子邮件和管理日历 — 通过标准输入/输出在本地运行。
## 工具
| 工具 | 功能 |
|------|-------------|
| `邮件列表` | 列出最近的电子邮件（文件夹、数量、未读筛选） |
| `读取邮件` | 按UID读取完整的电子邮件 |
| `搜索邮件` | 按发件人、主题、正文、日期范围搜索 |
| `草拟邮件` | 草拟回复或新电子邮件 |
| `发送邮件` | 发送已批准的电子邮件 |
| `自动回复` | 自动回复给白名单发件人 |
| `日历列表` | 列出即将到来的事件 |
| `创建日历` | 创建新事件 |
| `更新日历` | 更新或删除事件 |
## 前提条件
- Python 3.10+
- 谷歌账户
- 兼容MCP的客户端（Claude Code、Cursor等）
## 设置
### 身份验证流程（概述）
有两个**独立的身份验证系统**：
| 系统 | 用途 | 工作原理 |
|--------|----------|-------------|
| **Gmail应用密码** | IMAP（读取）+ SMTP（发送） | 来自谷歌账户设置的16字符密码 |
| **谷歌OAuth2** | 日历API | 基于浏览器的同意流程，保存令牌文件 |
您需要两者。应用密码用于电子邮件，OAuth2用于日历。
### 1. 安装依赖项
```bash
pip install mcp google-api-python-client google-auth-httplib2 google-auth-oauthlib
```
### 2. 创建Gmail应用密码（用于电子邮件）
Gmail使用IMAP/SMTP和应用密码 — 而不是您的真实谷歌密码。
**步骤：**
1. 前往 [谷歌账户安全](https://myaccount.google.com/security)
2. 启用 **两步验证** （必需 — 应用密码在没有它的情况下无法工作）
3. 前往 [应用密码](https://myaccount.google.com/apppasswords)
4. 选择应用： **邮件**，设备： **其他（自定义名称）** → 输入 "克劳德-2-邮件"
5. 点击 **生成** → 复制16字符密码（例如 `abcd efgh ijkl mnop`）
**原因：** 谷歌阻止 "不安全的应用程序"。应用密码是每个应用程序的令牌，绕过此限制。
### 3. 创建谷歌云项目（用于日历）
日历需要OAuth2。 这是一个多步骤的过程 — 按顺序执行：
**步骤A — 创建项目 + 启用API：**
1. 前往 [谷歌云控制台](https://console.cloud.google.com/)
2. 点击 **选择项目** → **新建项目** → 命名 → **创建**
3. 选择您的新项目
4. 前往 **API和服务 → 库**
5. 搜索 **"谷歌日历API"** → 点击它 → **启用**
**步骤B — 配置OAuth同意屏幕：**
1. 前往 **API和服务 → OAuth同意屏幕**
2. 用户类型： **外部** → **创建**
3. 填写：应用名称，用户支持电子邮件，开发者联系电子邮件
4. **保存并继续** 通过范围（不添加任何内容）→ **返回仪表板**
5. 在 **测试用户** 下 → **添加用户** → 添加您自己的电子邮件地址
**为什么是测试用户：** 在您的应用发布之前，只有测试用户可以授权它。 如果没有此步骤，OAuth将因 "access_blocked" 而失败。
**步骤C — 创建OAuth凭证：**
1. 前往 **API和服务 → 凭证**
2. **创建凭证** → **OAuth客户端ID**
3. 应用类型： **桌面应用** → 命名 → **创建**
4. 点击 **下载JSON** → 保存文件
**为什么是桌面应用：** MCP服务器在本地运行。 "桌面应用" 类型不需要重定向URI — 它使用本地主机回调。
### 4. 配置
```bash
mkdir -p ~/.config/claude-2-mail
cp config/config.template.json ~/.config/claude-2-mail/config.json
cp config/.secrets.template ~/.config/claude-2-mail/.secrets
cp config/credentials.json.template ~/.config/claude-2-mail/credentials.json
```
编辑每个文件：
**`~/.config/claude-2-mail/config.json`** — 您的电子邮件，显示名称，设置。
**`~/.config/claude-2-mail/.secrets`** — 您的应用密码：
```
export GMAIL_APP_PASSWORD="abcd efgh ijkl mnop"
```
**`~/.config/claude-2-mail/credentials.json`** — 粘贴下载的OAuth JSON。
锁定权限：
```bash
chmod 600 ~/.config/claude-2-mail/config.json
chmod 600 ~/.config/claude-2-mail/.secrets
chmod 600 ~/.config/claude-2-mail/credentials.json
```
### 5. 加载机密
添加到 `~/.bashrc` 或 `~/.zshrc`：
```bash
[ -f ~/.config/claude-2-mail/.secrets ] && source ~/.config/claude-2-mail/.secrets
```
重新加载： `source ~/.bashrc`
### 6. 在MCP客户端中注册
**克劳德代码** (`~/.mcp.json`)：
```json
{
"mcpServers": {
"gmail-calendar": {
"command": "python",
"args": ["/path/to/claude-2-mail/gmail_calendar_mcp.py"],
"env": {
"GMAIL_MAIL_CONFIG": "/home/YOUR_USER/.config/claude-2-mail/config.json"
}
}
}
}
```
### 7. 首次运行
首次使用日历会打开浏览器进行OAuth批准。 一次性 — 令牌保存以供将来使用。
## 故障排除
| 问题 | 解决方法 |
|---------|-----|
| `AUTHENTICATIONFAILED` （IMAP） | 重新生成应用密码。必须启用2FA。 |
| `invalid_client` （OAuth） | 检查credentials.json是否为桌面应用类型。 |
| `access_blocked` （OAuth） | 在OAuth同意屏幕中添加您的电子邮件作为测试用户。 |
| `Token expired` | 删除 `calendar_token.json`，重新授权。 |
| `Config not found` | 检查 `GMAIL_MAIL_CONFIG` 环境变量路径。 |
| `CredentialsWithRegionalAccessBoundary.refresh() missing argument` | 更新google-auth： `pip install --upgrade google-auth` |
| 缺少pip库 | `pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib` |
## 测试
```bash
pip install -e ".[dev]"
pytest tests/ -v
```
## 安全
- `.secrets` 中的应用密码（chmod 600），不在config.json或shell rc中
- OAuth令牌存储 chmod 600
- 在INFO级别，日志记录会遮蔽电子邮件/令牌/密码
- IMAP输入已转义以防止注入
- 仅限狭窄的OAuth范围
## 许可证
MIT.
