______       ________                                              __       __  ______  _______  
 /      \     |        \                                            |  \     /  \/      \|       \ 
|  ▓▓▓▓▓▓\    | ▓▓▓▓▓▓▓▓ ______   ______  ______ ____   _______     | ▓▓\   /  ▓▓  ▓▓▓▓▓▓\ ▓▓▓▓▓▓▓\
| ▓▓ __\▓▓    | ▓▓__    /      \ /      \|      \    \ /       \    | ▓▓▓\ /  ▓▓▓ ▓▓   \▓▓ ▓▓__/ ▓▓
| ▓▓|    \    | ▓▓  \  |  ▓▓▓▓▓▓\  ▓▓▓▓▓▓\ ▓▓▓▓▓▓\▓▓▓▓\  ▓▓▓▓▓▓▓    | ▓▓▓▓\  ▓▓▓▓ ▓▓     | ▓▓    ▓▓
| ▓▓ \▓▓▓▓    | ▓▓▓▓▓  | ▓▓  | ▓▓ ▓▓   \▓▓ ▓▓ | ▓▓ | ▓▓\▓▓    \     | ▓▓\▓▓ ▓▓ ▓▓ ▓▓   __| ▓▓▓▓▓▓▓ 
| ▓▓__| ▓▓    | ▓▓     | ▓▓__/ ▓▓ ▓▓     | ▓▓ | ▓▓ | ▓▓_\▓▓▓▓▓▓\    | ▓▓ \▓▓▓| ▓▓ ▓▓__/  \ ▓▓      
 \▓▓    ▓▓    | ▓▓      \▓▓    ▓▓ ▓▓     | ▓▓ | ▓▓ | ▓▓       ▓▓    | ▓▓  \▓ | ▓▓\▓▓    ▓▓ ▓▓      
  \▓▓▓▓▓▓      \▓▓       \▓▓▓▓▓▓ \▓▓      \▓▓  \▓▓  \▓▓\▓▓▓▓▓▓▓      \▓▓      \▓▓ \▓▓▓▓▓▓ \▓▓      
                                                             

Google Forms MCP

Production-grade Model Context Protocol (MCP) server for Google Forms, Drive, and Sheets automation.

Create, manage, and analyze Google Forms through an autonomous AI Planner that works with Claude, ChatGPT, Cursor, VS Code, Windsurf, Cline, Roo Code, and any MCP-compatible client.

✨ Features

🤖 Autonomous AI Planner (plan_form, get_template, validate_execution_plan)

• Automatically detects user intent and interviews the user for missing details.
• Validates the execution plan to prevent API errors and mutually exclusive field conflicts.
• Orchestrates Google Forms tools automatically to build complex forms.
• Includes pre-built templates (Hackathon, Survey, Quiz, RSVP).

📝 Form Management

• Create forms with title, description, and quiz mode
• Update form metadata and settings (progress bar, email collection, shuffle questions)
• Delete / Duplicate / Publish forms
• Search for forms in Google Drive

❓ All 11 Question Types Supported

• SHORT_ANSWER, PARAGRAPH, MULTIPLE_CHOICE, CHECKBOXES, DROPDOWN
• FILE_UPLOAD, LINEAR_SCALE, DATE, TIME
• MULTIPLE_CHOICE_GRID, CHECKBOX_GRID

📑 Sections & Layout

• Add, update, delete sections (page breaks) with conditional navigation
• Add images, videos, and text blocks

🧪 Quiz Mode

• Enable quiz grading with point values
• Set answer keys with correct answers and right/wrong feedback

📊 Response & Analytics Management

• Read all form responses (paginated) (get_responses, get_response)
• Get aggregated response summary statistics (get_response_summary)
• Export responses as CSV or JSON (export_responses)

📁 Google Drive Integration

• Create folders, move/copy/trash files, and search specific forms
• Manage permissions and share files with users, groups, or domains

📈 Google Sheets Integration

• Create spreadsheets, read/write/append data ranges, and export to CSV

🚀 Quickstart

1. Google Cloud Setup

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Go to APIs & Services → Library and enable these APIs:
   • Google Forms API
   • Google Drive API
   • Google Sheets API
4. Go to APIs & Services → Credentials
5. Create an OAuth 2.0 Client ID:
   • Application type: Desktop application
   • Name: Google Forms MCP
6. Note down your Client ID and Client Secret.

2. Get a Refresh Token (generate_token.py)

We provide an interactive, self-troubleshooting token generator helper script right inside the repository:

# Run interactively (will prompt for Client ID and Secret if not set)
python generate_token.py

# Or pass directly via command line arguments
python generate_token.py --client-id "your-client-id" --client-secret "your-client-secret"

# Or pass the downloaded JSON secrets file from GCP
python generate_token.py --file client_secret.json

The script will launch your browser, complete authentication, output your GOOGLE_REFRESH_TOKEN, and automatically offer to save it directly into your local .env file!

💡 Token Generator Troubleshooting (generate_token.py)

If you encounter issues generating your refresh token, check the common fixes below:

• Error 400 (redirect_uri_mismatch):

  1. Go to Google Cloud Console -> APIs & Services -> Credentials.
  2. Click on your OAuth 2.0 Client ID.
  3. Under Authorized redirect URIs, click + ADD URI and add exactly:
     http://localhost:8080/
  4. Click Save, wait 30–60 seconds for Google's servers to sync, and re-run python generate_token.py --port 8080.

• Access Blocked (This app's request is invalid / Error 403):

  1. Go to Google Cloud Console -> APIs & Services -> OAuth consent screen.
  2. If your app publishing status is set to Testing, scroll down to Test users.
  3. Click + ADD USERS and enter the exact Google email address you are logging in with.

• No Refresh Token Returned:

  1. Go to Google Account Connections.
  2. Click on Google Forms MCP and select Remove Access.
  3. Re-run python generate_token.py to prompt for a fresh offline token.

3. Install & Run

# Using uvx (recommended for instant execution)
uvx google-forms-mcp

# Or install from source locally using 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

# Or run as a standalone HTTP server (Streamable HTTP transport on port 8000)
export GOOGLE_FORMS_MCP_TRANSPORT="http"
python -m google_forms_mcp

4. Configure Your MCP Client

Option A: Running from Local Git Cloned Source (Include "cwd")

If you cloned this repository locally, you must include the "cwd" property so your client locates the project environment (.env) and Python executable cleanly:

{
  "mcpServers": {
    "google-forms": {
      "command": "python",
      "args": ["-m", "google_forms_mcp"],
      "cwd": "C:/absolute/path/to/google-forms-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Option B: Running via PyPI (uvx)

If running globally without cloning:

{
  "mcpServers": {
    "google-forms": {
      "command": "uvx",
      "args": ["google-forms-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Option C: Connecting via Custom Connector (Claude Web / Remote HTTP)

If running the server in http transport mode on http://127.0.0.1:8000/mcp:

1. Open your MCP Client connector settings.
2. Enter Remote MCP server URL: http://127.0.0.1:8000/mcp (Or your public HTTPS tunnel URL if connecting from cloud web apps like claude.ai).
3. Leave OAuth settings blank if your .env already contains GOOGLE_REFRESH_TOKEN.

Option D: Connecting with Claude Code CLI (claude mcp add)

If you use Anthropic's Claude Code command-line agent (claude), you can register the MCP server directly using the terminal or by creating a workspace .mcp.json:

# Register globally (`user` scope) via uvx:
claude mcp add google-forms -s user -- uvx google-forms-mcp

# OR register globally from local Git repo Python environment:
claude mcp add google-forms -s user -- C:/path/to/google-forms-mcp/.venv/Scripts/python.exe -m google_forms_mcp

Note: If credentials are not saved in a root .env file, pass them via environment variables when running Claude Code or define them directly inside ~/.claude.json under "mcpServers".

Option E: Connecting via GUI Settings (ChatGPT Desktop / Cursor / Windsurf GUI)

When configuring the server using graphical settings panels (like in ChatGPT Desktop Developer Mode or IDE GUI forms):

• ⚠️ IMPORTANT: Do not put arguments (-m google_forms_mcp) inside the Command to launch box!
• Configure the fields exactly as follows:
  • Command to launch:
    s:/google-forms-mcp/.venv/Scripts/python.exe (Or uvx if running globally)
  • Arguments: Click + Add argument twice:
    1. -m
    2. google_forms_mcp
       (If using uvx, add single argument google-forms-mcp)
  • Working directory:
    s:/google-forms-mcp
  • Environment variables: Add your 3 keys (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN).

🔧 Available Tools (44 Tools Total)

AI Planner & Prompts (3 tools)

Forms (19 tools)

Responses & Analytics (4 tools)

Drive (12 tools)

Sheets (7 tools)

⚙️ Configuration

⚠️ Known Limitations

These are Google Forms API limitations, not limitations of this MCP:

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

# Clone the repo
git clone https://github.com/your-org/google-forms-mcp.git
cd google-forms-mcp

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Lint & format
uv run ruff check src/ tests/
uv run ruff format src/ tests/

📄 License

MIT License — see LICENSE for details.