内容
# Gmail 和日历 MCP - 跨平台强化分支
本地模型上下文协议（MCP）服务器，支持多个 Gmail 账户和 Google 日历。该衍生版本源自 [DiegoMaldonadoRosas/gmail-mcp](https://github.com/DiegoMaldonadoRosas/gmail-mcp)，支持 macOS、Linux 和 Windows，并为邮箱操作和返回给 AI 客户端的内容添加了防护措施。
通过 [GitHub Pages](https://bpmorris22.github.io/gmail-mcp-hardened-cross-platform/) 查看浏览器格式化的公开设置和安全摘要，或在其源代码 [`docs/gmail-mcp-hardened-report.html`](docs/gmail-mcp-hardened-report.html) 中查看。
## 功能
- 多账户 Gmail 搜索、阅读、草稿、标签和回收站处理。
- 只读 Google 日历列表和事件搜索。
- 通过 `setup.sh` 进行 macOS/Linux 设置，通过 `setup.ps1` 进行 Windows 设置。
- 每个账户的 OAuth 客户端密钥路径，带有共享密钥的备用方案。
- 预览和一次性确认令牌，用于发送电子邮件、更改标签和将邮件移动到回收站。
- 附件发送和下载仅限于用户的 `Downloads`、`Documents` 或 `Desktop` 目录。
- 电子邮件和日历内容的非信任内容信封，清理意外错误和突变stderr审计条目。
## 要求
- Python 3.10 或更高版本。
- Claude Desktop 或另一个stdio MCP客户端。
- 具有启用 Gmail API 和 Google 日历 API 的 Google Cloud OAuth 桌面客户端。
## 安装
克隆您的公开分支，然后为您的平台运行设置命令。
macOS 或 Linux：
```bash
bash setup.sh
```
Windows PowerShell：
```powershell
powershell -ExecutionPolicy Bypass -File .\setup.ps1
```
脚本创建 `.venv`，安装依赖项，创建本地凭证目录，如果需要，从模板创建 `config.json`，并打印包含绝对路径的 MCP 配置片段。
## 配置账户
编辑生成的 `config.json`。建议为每个邮箱使用单独的 Google Cloud OAuth 客户端：
```json
{
"accounts": {
"personal": {
"email": "you@gmail.com",
"description": "个人 Gmail",
"client_secret": "./credentials/personal_client_secret.json"
},
"work": {
"email": "you@company.com",
"description": "工作 Gmail",
"client_secret": "./credentials/work_client_secret.json"
}
},
"credentials_dir": "./credentials"
}
```
对于单个共享 OAuth 客户端，请从每个帐户中省略 `client_secret`，并将下载的文件放在 `credentials/client_secret.json` 中。
然后进行身份验证：
```bash
.venv/bin/python setup_auth.py
```
在 Windows 上：
```powershell
.\.venv\Scripts\python.exe setup_auth.py
```
每个帐户的浏览器打开一次。更改 OAuth 范围或添加帐户后，请重新运行身份验证。
## MCP 客户端配置
使用设置脚本打印的 JSON。典型的 macOS/Linux 配置：
```json
{
"mcpServers": {
"gmail-hardened": {
"command": "/absolute/path/to/gmail-mcp/.venv/bin/python",
"args": ["/absolute/path/to/gmail-mcp/server.py"]
}
}
}
```
典型的 Windows 配置：
```json
{
"mcpServers": {
"gmail-hardened": {
"command": "C:\\absolute\\path\\to\\gmail-mcp\\.venv\\Scripts\\python.exe",
"args": ["C:\\absolute\\path\\to\\gmail-mcp\\server.py"]
}
}
}
```
Claude Desktop 配置位置：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows： `%APPDATA%\Claude\claude_desktop_config.json`
## 安全模型
电子邮件正文、主题行、发件人字段、草稿内容、日历名称和日历事件是外部输入。返回它们的工具包含一个警告，告诉 MCP 客户端将这些值视为数据而非指令。
所有写入工具首先返回预览：`gmail_send`、`gmail_create_draft`、`gmail_modify_labels`、`gmail_trash` 和 `gmail_download_attachment`。它们在没有调用时不会执行任何操作，调用时需要相同的输入、`confirm: true` 和预览返回的一次性 `confirmation_token`。确认的草稿会创建可见的 Gmail 内容，但不会发送邮件。
附件只能在 `~/Downloads`、`~/Documents` 或 `~/Desktop` 中读取或保存；在检查前解析路径以防止符号链接逃逸。服务器还拒绝附加其自己的凭证目录或常见的密钥/秘密文件类型。下载的附件字节保持不受信任。
令牌和客户端密钥保留在 `credentials/` 下，该目录被排除在 Git 之外。令牌写入请求用户仅有的文件权限（如果操作系统支持）。在 Windows 上，请将项目存储在用户配置文件中，并在计算机共享时检查目录 ACL。
OAuth 范围集仅限于 `gmail.modify`、`calendar.calendarlist.readonly` 和 `calendar.events.readonly`。此 MCP 不提供云文件上传或文件共享操作；这些操作应在具有单独同意和审计控制的单独服务中进行。
有关威胁模型和残留风险，请参见 [`SECURITY.md`](SECURITY.md)。
## 可用工具
| 领域 | 工具 |
| --- | --- |
| 账户 | `list_accounts` |
| Gmail 读取 | `gmail_get_profile`、`gmail_search`、`gmail_read_message`、`gmail_read_thread`、`gmail_list_drafts`、`gmail_list_labels` |
| Gmail 写入 | `gmail_send`、`gmail_create_draft`、`gmail_modify_labels`、`gmail_trash` |
| 附件 | `gmail_download_attachment` |
| 日历读取 | `calendar_list_calendars`、`calendar_list_events`、`calendar_search`、`calendar_get_event` |
## 发布
程序集工作区中的 `Mac/` 和 `Windows/` 目录被忽略，因为它们包含比较输入，可能包含机密或生成的文件。仅发布跟踪的根项目文件。有关合并决策，请参见 [`docs/COMPARISON.md`](docs/COMPARISON.md)，有关上游归属，请参见 [`NOTICE.md`](NOTICE.md)。
## 测试
安装依赖项后，运行：
```bash
python -m unittest discover -s tests
```
冒烟测试导入具有模板配置的服务器，并检查注册的预期跨平台工具表面；它不调用 Google API。
