内容
# py-mcp-google-toolbox
[](https://smithery.ai/server/@jikime/py-mcp-google-toolbox)   
一个MCP服务器，为AI助手提供强大的工具，以便与Google服务进行交互，包括Gmail、Google Calendar、Google Drive和Google Search。
<a href="https://glama.ai/mcp/servers/@jikime/py-mcp-google-toolbox">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@jikime/py-mcp-google-toolbox/badge" alt="Google Toolbox MCP server" />
</a>
## 概述
py-mcp-google-toolbox 提供以下与 Google 相关的功能：
- Gmail 操作（读取、搜索、发送、修改）
- Google Calendar 管理（事件创建、列出、更新、删除）
- Google Drive 交互（搜索、读取文件）
- Google Search 集成（搜索网页）
## 目录
- [前提条件](#prerequisites)
- [安装](#installation)
- [配置 MCP 设置](#configure-mcp-settings)
- [工具文档](#tools-documentation)
- [Gmail 工具](#gmail-tools)
- [日历工具](#calendar-tools)
- [云端硬盘工具](#drive-tools)
- [搜索工具](#search-tools)
- [开发](#development)
- [许可证](#license)
## 前提条件
1. **Python**: 安装 Python 3.12 或更高版本
2. **Google Cloud Console 设置**:
- 访问 [Google Cloud Console](https://console.cloud.google.com/)
- 创建一个新项目或选择一个现有项目
- 启用服务 API：
1. 进入 "APIs & Services" > "Library"
2. 搜索并启用 "Gmail API"
3. 搜索并启用 "Google Calendar API"
4. 搜索并启用 "Google Drive API"
5. 搜索并启用 "Custom Search API"
- 从 GCP 设置 OAuth 2.0 凭据：
1. 进入 "APIs & Services" > "Credentials"
2. 点击 "Create Credentials" > "OAuth client ID"
3. 选择 "Web application"
4. 记下 Client ID 和 Client Secret
- Client ID
- Client Secret
5. 下载密钥 json 文件并重命名为 credentials.json
- 生成一个 API 密钥
3. 访问 [Custom Search Engine](https://cse.google.com/cse/all) 并获取其 ID
## 安装
#### Git 克隆
```bash
git clone https://github.com/jikime/py-mcp-google-toolbox.git
cd py-mcp-google-toolbox
```
#### 配置
1. 安装 UV 包管理器：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. 创建并激活虚拟环境：
```bash
uv venv -p 3.12
source .venv/bin/activate # 在 MacOS/Linux 上
```
# 或者
.venv\Scripts\activate # 在 Windows 上
```
3. 安装依赖：
```bash
uv pip install -r requirements.txt
```
4. 获取刷新令牌（如果令牌已过期，可以运行此命令）
```bash
uv run get_refresh_token.py
```
这将会：
- 打开您的浏览器进行 Google OAuth 认证
- 请求以下权限：
- `https://www.googleapis.com/auth/gmail.modify`
- `https://www.googleapis.com/auth/calendar`
- `https://www.googleapis.com/auth/gmail.send`
- `https://www.googleapis.com/auth/gmail.readonly`
- `https://www.googleapis.com/auth/drive`
- `https://www.googleapis.com/auth/drive.file`
- `https://www.googleapis.com/auth/drive.readonly`
- 将凭据保存到 `token.json`
- 在控制台中显示刷新令牌
5. 环境变量：
```bash
cp env.example .env
vi .env
```
# 使用你的密钥进行更改
GOOGLE_API_KEY=你的_google_api_key
GOOGLE_CSE_ID=你的_custom_search_engine_id
GOOGLE_CLIENT_ID=你的_google_client_id
GOOGLE_CLIENT_SECRET=你的_google_client_secret
GOOGLE_REFRESH_TOKEN=你的_google_refresh_token
```
6. 将 credentials.json 复制到项目根文件夹 (py-mcp-google-toolbox)
#### 使用 Docker
1. 构建 Docker 镜像：
```bash
docker build -t py-mcp-google-toolbox .
```
2. 运行容器：
```bash
docker run py-mcp-google-toolbox
```
#### 使用本地
1. 运行服务器：
```bash
mcp run server.py
```
2. 运行 MCP Inspector：
```bash
mcp dev server.py
```
## 配置 MCP 设置
将服务器配置添加到您的 MCP 设置文件中：
#### Claude桌面应用程序
1. 通过 [Smithery](https://smithery.ai/server/@jikime/py-mcp-google-toolbox) 自动安装：
```bash
npx -y @smithery/cli install @jikime/py-mcp-google-toolbox --client claude
```
2. 手动安装
打开 `~/Library/Application Support/Claude/claude_desktop_config.json`
将以下内容添加到 `mcpServers` 对象中：
```json
{
"mcpServers": {
"Google Toolbox": {
"command": "/path/to/bin/uv",
"args": [
"--directory",
"/path/to/py-mcp-google-toolbox",
"run",
"server.py"
]
}
}
}
```
#### Cursor IDE
打开 `~/.cursor/mcp.json`
将以下内容添加到 `mcpServers` 对象中：
```json
{
"mcpServers": {
"Google Toolbox": {
"command": "/path/to/bin/uv",
"args": [
"--directory",
"/path/to/py-mcp-google-toolbox",
"run",
"server.py"
]
}
}
}
```
#### for Docker
```json
{
"mcpServers": {
"Google Toolbox": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"py-mcp-google-toolbox"
]
}
}
}
```
## 工具文档
### Gmail 工具
- `list_emails`: 列出 Gmail 收件箱中最近的电子邮件，并提供过滤选项
- `search_emails`: 执行高级 Gmail 搜索，并详细检索电子邮件内容
- `send_email`: 撰写并发送电子邮件，支持抄送 (CC) 和密送 (BCC) 收件人
- `modify_email`: 通过修改标签更改电子邮件状态（已读/未读、归档、删除）
### 日历工具
- `list_events`: 检索指定时间范围内即将发生的日历事件
- `create_event`: 创建新的日历事件，包括与会者、地点和描述
- `update_event`: 修改现有的日历事件，支持灵活的参数更新
- `delete_event`: 根据事件 ID 删除日历事件
### 驱动工具
- `read_gdrive_file`: 从 Google Drive 文件中读取和检索内容
- `search_gdrive`: 在 Google Drive 中搜索文件，支持自定义查询
### 搜索工具
- `search_google`: 执行 Google 搜索并返回格式化的结果
## 开发
对于本地测试，您可以使用包含的客户端脚本：
```bash
```
# 示例：列出邮件
uv run client.py list_emails max_results=5 query="is:unread"
# 示例：搜索邮件
uv run client.py search_emails query="from:test@example.com"
# 示例：发送电子邮件
uv run client.py send_email to="test@example.com" subject="test mail" body="Hello"
# 示例：修改电子邮件
uv run client.py modify_email id=MESSAGE_ID remove_labels=INBOX add_labels=ARCHIVED
# 示例：列出事件
uv run client.py list_events time_min=2025-05-01T00:00:00+09:00 time_max=2025-05-02T23:59:59+09:00 max_results=5
# 示例：创建事件
uv run client.py create_event summary="new event" start=2025-05-02T10:00:00+09:00 end=2025-05-02T11:00:00+09:00 attendees="user1@example.com,user2@example.com"
# 示例：更新事件
uv run client.py update_event event_id=EVENT_ID summary="更新事件" start=2025-05-02T10:00:00+09:00 end=2025-05-02T11:00:00+09:00 attendees="user1@example.com,user2@example.com"
# 示例删除事件
uv run client.py delete_event event_id=EVENT_ID
# 示例：搜索 Google
uv run client.py search_google query="what is the MCP?"
# 示例：搜索 Google Drive
uv run client.py search_gdrive query=mcp
# 示例：读取文件
uv run client.py read_gdrive_file file_id=1234567890
```
## 许可证
MIT 许可证
