内容
# Gmail-MCP
一个遵循模型上下文协议（MCP）的服务器，通过该协议暴露Gmail的功能。这样，支持MCP的客户端（例如 **Omnexus**、Claude Desktop、Claude Code等）可以代表用户搜索线程、阅读消息、管理标签和草拟回复。
## 工具列表
| 工具 | 用途 |
| --- | --- |
| `search_threads` | 使用Gmail的查询语法搜索线程（`from:alice newer_than:7d`等）。 |
| `get_thread` | 获取线程的主题、参与者和每条消息的正文。 |
| `list_labels` | 列出所有系统和用户标签及其ID。 |
| `get_label_id` | 将标签名称解析为其ID（不区分大小写）。 |
| `add_thread_label` / `remove_thread_label` | 在线程上应用或删除标签。 |
| `create_draft` | 保存草稿（**不**发送）。 |
请求的OAuth范围：`gmail.readonly`、`gmail.compose`、`gmail.labels`、`gmail.modify`。故意不授权发送邮件。
## 设置
需要Python 3.14和 [uv](https://docs.astral.sh/uv/)。
1. **创建Google OAuth客户端。** 在 [Google Cloud Console](https://console.cloud.google.com/) 中，启用Gmail API并创建一个OAuth 2.0 **桌面应用程序** 客户端。下载JSON文件。
2. **放置凭证文件。** 将JSON文件保存到 `~/.config/gmail-mcp/gmail_credentials.json`，或将 `GMAIL_CREDENTIALS_PATH` 环境变量指向它。
3. **安装依赖项。**
```bash
uv sync
```
4. **授权一次。** 这将打开浏览器，完成OAuth流程，并在 `~/.config/gmail-mcp/gmail_token.json` 处缓存刷新令牌（也可以使用 `GMAIL_TOKEN_PATH` 重写）。
```bash
uv run server.py --gmail-auth
```
在将服务器连接到MCP客户端之前运行此命令——在stdio传输下，浏览器握手将挂起客户端。
## 运行
```bash
# stdio（默认；大多数MCP客户端期望）
uv run server.py
# 可流式HTTP
uv run server.py --transport streamable-http --host 127.0.0.1 --port 8000
```
### Claude Desktop / Claude Code 配置
```json
{
"mcpServers": {
"gmail": {
"command": "uv",
"args": ["--directory", "/path/to/Gmail-MCP", "run", "server.py"]
}
}
}
```
## 环境变量
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `GMAIL_CREDENTIALS_PATH` | `~/.config/gmail-mcp/gmail_credentials.json` | 来自Google Cloud Console的OAuth客户端配置。 |
| `GMAIL_TOKEN_PATH` | `~/.config/gmail-mcp/gmail_token.json` | 缓存的用户令牌（在首次身份验证时创建，自动刷新）。 |
项目根目录中的`.env`文件将在启动时加载。
## 许可证
参见 [LICENSE](LICENSE)。
