内容
text
______ ________ __ __ ______ _______
/ \ | \ \ / \/ \
| ▓▓▓▓\ ▓▓▓▓▓▓ ______ ______ ____ _______ ▓▓\ ▓▓ ▓▓▓▓▓▓\ ▓▓▓▓▓▓▓\
| ▓▓ __\▓▓ | ▓▓__ / \ / \| \ \ / \ | ▓▓▓\ / ▓▓ \▓▓ __/ ▓| ▓ \ |▓ \ ▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓\ ▓▓▓▓▓▓▓ ▓▓ ▓▓ ▓ | ▓▓ ▓▓
| ▓▓ \▓ | ▓▓▓▓ | ▓▓▓ \▓▓ ▓▓ | ▓▓ | \▓▓ \ | \▓▓ ▓▓| ▓▓▓▓▓
| ▓▓__| ▓▓ | ▓ | ▓ ▓▓ | | ▓▓▓_\▓▓▓▓▓▓ | ▓▓ \▓▓ ▓▓ __/ \ ▓▓
\ ▓ | ▓ \▓▓▓▓ ▓▓ | ▓ ▓▓▓ ▓ |▓ \▓▓\▓▓ ▓ \▓▓▓▓▓ \▓ \▓▓▓▓▓▓ \▓▓▓▓ \▓▓\▓▓▓▓▓▓▓ \▓▓ \▓▓ \▓▓▓▓▓▓ \▓▓
```
<meta name="google-site-verification" content="qj4RNAx2OhoRZ6F4UBqZwGFZxhDIMoel8" />
# Google 表单 MCP
[](https://github.com/your-org/google-forms/releases/tag/v1.0)
[
[](https://opensource.org/licenses/MIT)
3.10+://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[
[
**适用于 Google 表单、 自动化生产的 Protocol（MCP）**
通过与 Claude、ChatGPT、Cursor、VS Code、Windsurf、Coo Code 等任何 MCP 兼容的客户端 AI 计划器，创建、管理和分析 Google<div align="center <br />
="assets/student_form_demo.png" alt="AI 助手使用 Google 表单 MCP 自动创建学生信息收集表单" width="800" />
/>
<i>在几秒从 AI 客户端构建完整的 Google 表单。</i></pdiv>
---
## ✨ 🤖 自主 AI 计划器（`plan_form`、`get_templatevalidate_execution_plan`）
- 自动检测用户意图并询问用户以获取缺失的详细信息。
- 验证执行防止 API 错误和相互排斥的字段冲突。
- 自动协调 Google 表单工具以构建复杂的表单。
- 包括预建模板（`Hackathon`、`Survey`、`Quiz`、`RSVP`）。
### 📝 表单管理
- **创建** 具有标题、描述和测表单
- **更新** 表单和设置（进度条、电子邮件收集、随机排列问题）
- **删除** / **复制**发布** 表单 **搜索** Google Drive
### ❓ 11 种问题类型
- `SHORT_PARAGRAPH`、`MULTIPLE_CHOICE`、`CHECKBOXES`、`PDOWN`
- `FILE_UPLOAD`、`LINEAR_SCALE`、`TIME`
MULTIPLE_CHO、`CHECKBOX_GRID`
### 📑 分节和布局
- 添加、分节（）并设置条件 添加图片、视频块
### 测验模式 启用测验设置分数值
-并提供正确
### 响应和数据分析- 读取所有表单响应（分页）（`get_res、`get_response` 获取聚合响应摘要（`get_response_summary`）
- 将响应导出 JSON（`ponses`）
Google Drive - 创建文件夹、移动/删除文件并表单
- 管理与用户、群域共享文件
📈 Google Sheets 集成 创建电子表格、写入/追加数据导出为 CSV
🚀 快速入门
### 1. 设置
1. 前 Cloud 控制台console.cloud.google.com/)
2. 创建一个或选择现有3. 前往服务 → 库**以下 API：
Google 表单 API - **Google Drive - **Google**
4. 前服务 → . 创建一个2.0 ID**：
应用程序类型：****
- `Google 表单6. 记录下您的 **客户端 ID** 和 ****。
---
### 获取刷新令牌（`generate_token.py`）
我们提供一个交互式、自我故障排除的令牌生成器帮助脚本，直接在存储库中：
```bash
# 交互式运行（如果未设置，将提示输入客户端 ID 和密钥）
python generate_token.py
# 或通过命令行传递
python generate --client-id "-id" --client-secret-client-secret"
# 或传递从 GCP 下载的文件
python generate_token.py --file client```
脚本将，完成身份验证 `GOOGLE_TOKEN`，并自动为您提供将其直接保存 `.env` 文件
#### 💡牌生成器故障`generate_token.py如果您在生成时遇到问题以下常见解决方法：错误 400（`redirect_uri_mismatch**：
1. 前往 Google Cloud 控制台 -> **API 和服务 -> 凭证**。
2. 点击您的 **OAuth 2.0 客户端 ID**。
3. 在 **授权重定向 URI** 下+ 添加 URI**：
`http://localhost:8080/`
4. 点击 **保存**，30-60 秒让 Google 服务器同步，然后重新运行 `python generate_tokenport 8080* **访问受阻（`This app's request is invalid` / 错误 403）**：
1. 前往 Google Cloud 控制台 -> **API 和服务 -> OAuth 同意屏幕**。
2. 如果您的状态设置为 **测试中**，请向下滚动到 **测试用户** 3. 点击 **+ 添加用户**您登录时使用的确切 Google 电子邮件地址 **未返回刷新令牌**：
1. 前往 [Google 账户连接](myaccount.google.com/connections)。
2. 点击 `Google 表单 MCP` 并选择 **移除**。
3. 重新运行 `python generate_token.py` 以提示获取新的离线令牌。
---
### 3. 安装和运行
```bash
# 使用 uvx（推荐快速执行）
uvx google-forms-mcp
# 或使用 uv / pip 从源代码本地安装
git clone https://github.com/your-org/google-forms-mcp.git
cd google-forms-mcp
uv sync
uv run python -m google_forms_mcp 或作为独立的 HTTP 服务器运行（8000 上的 Streamable HTTP 传输 GOOGLE_FORMS_MCP_TRANSPORT="http"
python -m google_forms_mcp
```
---
### 4您的 MCP 客户端
#### 选项 A：从本地克隆的 Git 源运行（包括 `"cwd"`）
如果您在本地克隆了此存储库，**您必须包含 `" 属性**，以便您的客户端可以正确定位项目环境（`.env`）和 Python 可执行文件：
```json
{
cpServers": {
"google-forms": {
"command":",
" ["-m", "google_forms"],
"cwd": "C:/absolute/google-forms-m "env "GOOGLE_CLIENT_ID": "your-client-id",
"GOOGLE_CLIENT_SECRET": "your-client-secret",
"GOOGLE_REF": "your-refresh-token"
}
}
}
```
#### 选项 B：通过 PyPI 运行（x`）
如果全局运行且不克
```json "mcpServers": {
"google-forms": {
"command": "uvx",
"args": ["google-forms-mcp"],
"env": {
"GOOGLE_CLIENT_IDyour-client-id",
"GOOGLE_CLIENT_SECRET": "your-client-secretGOOGLE_REFRESH_TOKEN": "your }
}
}
```
#### 选项 C：器连接（ Web / 远程 HTTP）
如果在 `http模式下运行为 `http.0.1:8000/mcp`：
1. 打开您的 MCP 客户端连接器设置。
2. 输入 **远程 MCP 服务器 URL**：`http://127.0.0.1:8000/mcp` *(或您的公共 HTTPS 隧道 URL，如果从 `claude.ai` 等 应用程序连接)*。
3. 如果您的` 已包含OGLE_REFRESH，请将 OAuth空。
#### 选项 D：使用 连接（aude mcp add如果您使用 AnthropicClaude Code** 命令行代理（aude`），可以直接中或通过创建mcp.json MCP 服务器：
# 通过 在全局范围内注册（`user` 范围claude mcp-forms -s uvx google-forms# 或从 仓库的 Python全局注册：
claude mcp add google-forms -- C:/path/to/google-forms-m/Scripts/pythonm google_cp
```
*注意：如果凭证未保存在` 文件中环境变量传递直接在 `~aude.json` 中 `"mcpServers*
#### 选项 GUI 设置GPT 桌面 / Wind使用图形设置时（例如GPT 桌面版 IDE 图中）：
* **⚠️ 重要：** 请勿在 **启动命令** 框中添加参数（`-m google_mcp`）！
* 按照以下方式字段：
- **启动命令：**
s:/google-forms-mcp/.venv/S.exe` *(或使用 `uvx`)*
- **参数 **+ 两次：
1. `-m2. `google_forms_mcp *(如果使用 ``，添加单个-forms-mcp`)*
- **工作目录：**
`google-forms-m - **环境 添加您的 （`GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET`、`GOOGLE_REFRESH_TOKEN`）。
---
## 🔧 可用工具（共 44 个工具）
### AI 计划器和提示（3 个工具）
| 工具 | 描述 |
|:-----|:------------|
| `plan_form` |用户并自主问题 |
| `get_template` | 获取预建的 JSON 表单模板（`Hackathon`、`Quiz`、`RSVP`| `validate_execution 在 API 执行问题序列和规则单（19 个工具）
| |
|:-----|:------------|
| `create_form` | 创建新的单 |
|_form` | 检索完整的表单结构 |
|_info` | 更新标题和描述 |
delete_form` | 删除（移至回收站） |
|_form` | 复制现有表单 |
|_form` | 发布接受响应 |
| `add_question` | 添加 11 种问题类型 |
|_question` | 修改现有问题 |
| `delete 删除问题 `move_question` | 重新排序问题duplicate_question`复制现有问题 |
| `set_question_branch | 根据选项进行| `add | 添加分节（分页符） |
|_section` |节标题/描述 |
| `delete_section`分节 |
set_section_navigation`分节导航操作 `update_settings 更新表单设置（、进度条等） |
| `add_media` | 添加图片 |
| `add_text_item` | 添加 |
### 响应和（4 个工具）
| 工具 |
|:-----|:------------|
| `get` | 列出所有响应（分页） `get_response` ID 获取单个响应 |
| `get_response_summary` | 获取所有问题的聚合统计数据 |
|_responses` | CSV 或### Drive（12）
| 工具 | 描述 |
|:-----|
| `create_folder` | 创建 Drive 文件夹 |
| `search_forms` | 专门搜索 Google 表单 |
| `search_files` | 搜索任意文件 |
| `move_file` | 移动到另一个文件夹 |
| `copy_file` | 复制文件 |
|_file` | 移至回收站 |
| `restore_file` | 从回收站恢复 |
| `get_file | 获取元数据 |
share_file` | 与用户/群组共享 `transfer_ownership` | 转让权 |
| `get_permissions` | 列出 |
| `remove_permission` | 删除权限 Sheets（7）
| 工具 | 描述 |
|:-----|:------------|
| `create_spreadsheet` |表格 |
| `readsheet_info` | 获取电子表格 |
| `_data` | 读取| `_data` | 数据 |
|_sheet_data` | 追加行 |
|_sheet_data` | 清除范围数据 |
| `export_sheet_csv` | 导出为 CSV## ⚙️| 环境变量 | 默认值 |
|:----|:----GOOGLE_CLIENT_ID` | OAuth 2.0 客户端 ID | 必需 |
| `GOOGLE_CLIENT_SECRET OAuth 2 客户端密钥 | 必需 |
| `GOOGLE_REFRESH_TOKEN` | 预先获取的 | 必需 |
| `GOOGLECRETS_FILE` | 客户端密钥 JSON 文件路径 | — |
GOOGLE_FORMS_MCP_TRANSPORT`模式：` `http `stdio` |
OGLE_FORCP_PORT` 端口（当 时） | `8000` |
| `GO_MCP | 日 `INFO` `GOOGLE_FORMS_MCP_TOKEN_PATH令牌 | `~/.google-forms-mcp/token.json` |
---
## ⚠️ 已知限制
这些是 Google 表单 API 的限制，而不是此 MCP 的限制：
| 功能 | 状态 |
|:--------|:-------|
| 主题自定义（颜色、字体、标题） | ❌ 不支持 API |
| 删除响应 |支持 API |
| 到 Sheets | ❌ 不支持 API（需要 UI/Apps） |
| 设置 | ✅ 现支持 |
---
## 🤝 贡献
欢迎贡献！请参阅 `ING.md` 了解指南。
# 克隆仓库
git clone https://github.com/your-org/googlecp.git
cd google-forms-mcp
# 安装依赖
uv sync --dev
# 运行测试
uv run pytest 整理和格式化
uv run check src/ tests/
uv run format src/ tests/
```
---
## 📄 许可证
MIT 许可证 —阅 `LICENSE` 了解详情。
```
