AI导哈

谷歌工作区命令行工具

用于管理Google工作区的命令行工具，支持创建表单、添加问题、导出响应和读取电子表格。

  • by maksdizzy
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 maksdizzy/google-forms-mcp

使用说明

谷歌工具CLI

用于管理谷歌工作区的命令行工具-创建表单、添加问题、导出回复、阅读电子表格。

特性

  • 全表单管理 -创建、更新、删除、复制表单
  • 所有问题类型 -支持12种Google Forms问题类型
  • 响应导出 -将响应导出到CSV
  • 谷歌表格 -读取和导出电子表格数据
  • YAML模板 -从简单的YAML文件创建复杂的表单
  • 交互式OAuth向导 -非技术用户易于设置
  • 光标技能 -在Cursor IDE中充当AI代理技能

快速开始

1.安装

# Clone the repository
git clone https://github.com/maksdizzy/google-forms-cli
cd google-forms-cli

# Install with uv
uv sync

2.设置OAuth

# Run interactive setup wizard
uv run gtools auth setup

向导将指导您完成以下操作：

  1. 在Google Cloud控制台中创建OAuth凭据
  2. 获取刷新令牌
  3. 将凭据保存到 .env

3.使用

# List your forms
uv run gtools forms list

# Create a new form
uv run gtools forms create "My Survey"

# Add a question
uv run gtools forms add-question FORM_ID --type MULTIPLE_CHOICE --title "Rate us" --options "1,2,3,4,5"

# Export responses
uv run gtools forms export FORM_ID --output responses.csv

# Read a spreadsheet
uv run gtools sheets read SPREADSHEET_ID

CLI结构

gtools
├── auth          # Authentication management
│   ├── setup     # Interactive OAuth wizard
│   └── check     # Verify credentials
├── forms         # Google Forms operations
│   ├── list      # List all forms
│   ├── create    # Create new form
│   ├── get       # Get form details
│   ├── update    # Update form
│   ├── delete    # Delete form
│   ├── duplicate # Copy form with personalization
│   ├── link      # Get share links
│   ├── add-question    # Add question
│   ├── delete-question # Remove question
│   ├── move-question   # Reorder question
│   ├── add-section     # Add section break
│   ├── responses       # List responses
│   ├── export          # Export to CSV
│   ├── apply           # Create from YAML
│   └── export-template # Export to YAML
└── sheets        # Google Sheets operations
    ├── info      # Get spreadsheet metadata
    ├── list      # List sheets
    └── read      # Read data (table/CSV/JSON)

命令

认证

命令 描述
gtools auth setup 交互式OAuth设置
gtools auth check 验证凭据

表单管理

命令 描述
gtools forms list 列出所有表单
gtools forms create "Title" 创建新表单
gtools forms get FORM_ID 获取表单详细信息
gtools forms update FORM_ID 更新表单
gtools forms delete FORM_ID 删除表单
gtools forms duplicate FORM_ID 复制表格
gtools forms link FORM_ID 获取共享链接

问题

命令 描述
gtools forms add-question 添加问题
gtools forms delete-question 删除问题
gtools forms move-question 重新排序问题
gtools forms add-section 添加分段符

回复

命令 描述
gtools forms responses FORM_ID 列出回复
gtools forms export FORM_ID 导出到CSV

模板

命令 描述
gtools forms apply template.yaml 从模板创建
gtools forms export-template FORM_ID 导出到YAML

谷歌表格

命令 描述
gtools sheets info SPREADSHEET_ID 获取电子表格元数据
gtools sheets list SPREADSHEET_ID 列表表
gtools sheets read SPREADSHEET_ID 读取数据

问题类型

# Text questions
--type SHORT_ANSWER
--type PARAGRAPH

# Choice questions (use --options)
--type MULTIPLE_CHOICE --options "A,B,C"
--type CHECKBOXES --options "X,Y,Z"
--type DROPDOWN --options "1,2,3"

# Scale questions
--type LINEAR_SCALE --low 1 --high 5
--type RATING --high 5

# Other
--type DATE
--type TIME

YAML模板

从YAML文件创建表单：

form:
  title: "Customer Feedback"
  description: "Share your experience"

questions:
  - type: SHORT_ANSWER
    title: "Your name"
    required: true

  - type: MULTIPLE_CHOICE
    title: "Satisfaction"
    options: [Excellent, Good, Fair, Poor]
    required: true

  - type: PARAGRAPH
    title: "Comments"

申请方式：

uv run gtools forms apply feedback.yaml

看 templates/examples/ 更多示例：

  • feedback_form.yaml -员工反馈调查
  • event_registration.yaml -活动登记表
  • customer_satisfaction.yaml -客户满意度调查

OAuth设置详细信息

先决条件

  1. 首选 谷歌云控制台
  2. 创建新项目
  3. 启用 谷歌表单API, Google Drive API，以及 谷歌网页API
  4. 创建OAuth 2.0凭据（桌面应用程序）

获取刷新令牌

选项1:OAuth游乐场（推荐）

  1. 首选 OAuth游乐场
  2. 单击设置→ 勾选“使用您自己的OAuth凭据”
  3. 输入您的客户端ID和客户端密码
  4. 添加作用域：
    • https://www.googleapis.com/auth/forms.body
    • https://www.googleapis.com/auth/forms.responses.readonly
    • https://www.googleapis.com/auth/drive.file
    • https://www.googleapis.com/auth/spreadsheets.readonly
  5. 授权和兑换代币
  6. 复制刷新令牌

选项2：交互式向导

uv run gtools auth setup

适用于光标/AI代理

该工具旨在作为Cursor IDE中AI代理的一项技能。

看 skill.md 获取完整的代理说明，包括：

  • 所有命令的快速参考
  • 常见工作流程
  • 错误处理

项目结构

google-forms-cli/
├── src/gtools/
│   ├── __init__.py       # Package init
│   ├── cli.py            # Main CLI entry point
│   ├── templates.py      # YAML template engine
│   ├── core/
│   │   ├── auth.py       # OAuth + interactive wizard
│   │   ├── base.py       # BaseAPI class
│   │   └── scopes.py     # OAuth scopes
│   ├── forms/
│   │   ├── api.py        # Google Forms API wrapper
│   │   ├── models.py     # Pydantic models
│   │   └── commands.py   # Forms CLI commands
│   └── sheets/
│       ├── api.py        # Google Sheets API wrapper
│       ├── models.py     # Pydantic models
│       └── commands.py   # Sheets CLI commands
├── templates/
│   └── examples/         # Example YAML templates
├── skill.md              # Cursor agent instructions
├── pyproject.toml        # Project configuration
└── README.md             # This file

向后兼容

遗产 gforms 命令仍然用作别名：

# Both commands work identically
uv run gforms forms list
uv run gtools forms list

故障排除

OAuth错误：

uv run gtools auth check  # Verify credentials
uv run gtools auth setup  # Reconfigure if needed

API错误：

  • 使用验证表单ID uv run gtools forms list
  • 在Google云控制台中检查API配额

安全

  • .env 文件被gitignore（从未提交）
  • 刷新令牌提供帐户访问权限-保持安全
  • 撤销访问权限：https://myaccount.google.com/permissions

许可证

麻省理工学院

相关 MCP