Google Forms MCP Server

Simple and reliable MCP server for Google Forms management. Optimized for HR managers creating feedback forms.

Features

✅ 15 essential tools (forms, questions, responses) ✅ All 12 Google Forms question types ✅ OAuth via .env (simple setup) ✅ Auto-publish forms ✅ CSV export for Excel ✅ ~640 lines of Python code

Quick Start

1. Install Dependencies

2. Get OAuth Credentials

Create OAuth Client:

1. Go to https://console.cloud.google.com

2. Create project → Enable Forms API & Drive API

3. Create OAuth client ID (Desktop app)

4. Save client_id and client_secret

Get Refresh Token (Option A - Easiest):

1. Go to https://developers.google.com/oauthplayground/

2. Settings → Use your own OAuth credentials

3. Select scopes:

   • https://www.googleapis.com/auth/forms.body

   • https://www.googleapis.com/auth/forms.responses.readonly

   • https://www.googleapis.com/auth/drive.file

4. Authorize → Exchange code → Copy refresh_token

Get Refresh Token (Option B - Script):

3. Create .env File

4. Run Server

5. Configure Claude Code

Add to ~/.config/claude/config.json:

Important: Replace the paths above with your actual project location. Use the virtual environment's Python interpreter (venv/bin/python).

Available Tools

Forms Management

• forms_create - Create new form

• forms_list - List all forms

• forms_get - Get form details

• forms_update - Update form

• forms_delete - Delete form

Questions

• questions_add - Add question (12 types)

• questions_update - Update question

• questions_delete - Delete question

• questions_move - Reorder question

Sections

• sections_add - Add section/page break

Responses

• responses_list - List all responses

• responses_get - Get specific response

• responses_export_csv - Export to CSV

Utilities

• forms_duplicate - Copy form

• forms_get_link - Get public link

Question Types Supported

1. SHORT_ANSWER - Short text

2. PARAGRAPH - Long text

3. MULTIPLE_CHOICE - Radio buttons

4. CHECKBOXES - Multiple selection

5. DROPDOWN - Dropdown menu

6. LINEAR_SCALE - 1-5, 1-10 scale

7. DATE - Date picker

8. TIME - Time picker

9. FILE_UPLOAD - File upload

10. MULTIPLE_CHOICE_GRID - Radio grid

11. CHECKBOX_GRID - Checkbox grid

12. RATING - Star/heart rating

Usage Example

Project Structure

Architecture

Troubleshooting

OAuth Errors:

• Check .env has all 3 credentials

• Verify scopes are correct

• Regenerate refresh_token if expired

API Errors:

• Enable Forms API in Cloud Console

• Enable Drive API in Cloud Console

• Check API quotas

MCP Connection:

• Verify python path in config

• Test with python main.py directly

• Check MCP SDK version >=0.9.0

Security

• .env file is gitignored

• Refresh token gives full account access

• Token auto-refreshes every hour

• Revoke: https://myaccount.google.com/permissions

For AI Agents / Claude Code

⚠️ IMPORTANT: This MCP server provides direct access to Google Forms. When working with this project:

• ✅ DO: Call MCP tools directly (forms_create, questions_add, etc.)

• ❌ DON'T: Use Context7/WebSearch to research Google Forms API

• ❌ DON'T: Look up JSON schemas or API documentation

Why? The API wrapper is already implemented. Just use the tools!

Quick Test: Try forms_list with no parameters to verify MCP server is working.

Known Issues & Analysis

⚠️ questions_add: Code is correct (verified against official docs), but may fail in some test environments. See claudedocs/GOOGLE_FORMS_API_FIXES.md for:

• Root cause analysis with official Google documentation

• Evidence-based fix recommendations

• Troubleshooting steps

Development

See SPECIFICATION.md for complete implementation details.

License

MIT