Google Forms MCP

MCP server for the Google Forms API: create forms, add and edit questions, publish, read responses and set up push notifications for new submissions — from Claude, Cursor, Codex and other AI clients, in natural language.

Ask your assistant to "make a customer-feedback survey with a rating question and publish it", "show me yesterday's responses", or "close the form for responses" — it drives the Forms API for you, from a blank form to response analysis.

Quick start

1. Get OAuth credentials for the Google Forms API.

2. Add the server — for example, in Claude Code (other clients):

   claude mcp add google-forms \
     -e GOOGLE_FORMS_CLIENT_ID=your_client_id \
     -e GOOGLE_FORMS_CLIENT_SECRET=your_client_secret \
     -e GOOGLE_FORMS_REFRESH_TOKEN=your_refresh_token \
     -- npx -y mcp-google-forms@latest
   

3. Ask the assistant: "Create a form called 'Team lunch survey' with a dropdown of three restaurants and publish it."

Tools

Plus resilience built in: automatic OAuth token refresh (including on 401), retries with backoff on 429 (and on 5xx/network errors for reads only — writes are never replayed), a request timeout, and an SSRF guard so the token can't leak to a foreign host.

Example prompts

• "Create an RSVP form for the offsite, ask for name, meal preference (veg/meat/fish) and arrival date, then publish it and give me the link."
• "Turn the 'Onboarding quiz' form into a quiz and make every question required."
• "How many responses came in since Monday? Summarize the free-text feedback."
• "Stop accepting responses on the feedback form."

Limitations (the API's, not the server's)

• Responses are read-only. The Forms API cannot submit or edit responses — there is no such endpoint, so this server has no submit tool either.
• API-created forms start unpublished and don't accept responses until published — use publish: true on create_form or set_publish_settings. Legacy forms (from before the publish model) don't support set_publish_settings at all.
• File-upload questions can't be created via the API (existing ones are readable).
• Quotas are per minute (reads 975/project, list_responses 450, writes 375); the server backs off on 429 automatically.

Installation

Requires Node.js 20+ (runs via npx, no separate install).

claude mcp add google-forms \
  -e GOOGLE_FORMS_CLIENT_ID=your_client_id \
  -e GOOGLE_FORMS_CLIENT_SECRET=your_client_secret \
  -e GOOGLE_FORMS_REFRESH_TOKEN=your_refresh_token \
  -- npx -y mcp-google-forms@latest

{
  "mcpServers": {
    "google-forms": {
      "command": "npx",
      "args": ["-y", "mcp-google-forms@latest"],
      "env": {
        "GOOGLE_FORMS_CLIENT_ID": "your_client_id",
        "GOOGLE_FORMS_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_FORMS_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "mcpServers": {
    "google-forms": {
      "command": "npx",
      "args": ["-y", "mcp-google-forms@latest"],
      "env": {
        "GOOGLE_FORMS_CLIENT_ID": "your_client_id",
        "GOOGLE_FORMS_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_FORMS_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "servers": {
    "google-forms": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-forms@latest"],
      "env": {
        "GOOGLE_FORMS_CLIENT_ID": "your_client_id",
        "GOOGLE_FORMS_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_FORMS_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Getting credentials

The Forms API has no API-key access — every call needs OAuth 2.0. One-time setup, ~10 minutes:

1. Create a Google Cloud project (or reuse one) at console.cloud.google.com, then enable the Google Forms API: APIs & Services → Library → Google Forms API → Enable.
2. Configure the OAuth consent screen (APIs & Services → OAuth consent screen): choose External, fill in the app name and your email, and add your Google account under Test users (in Testing mode only listed users can authorize — no app verification needed).
3. Create an OAuth client (APIs & Services → Credentials → Create credentials → OAuth client ID), application type Desktop app. Save the client ID and client secret.
4. Mint a refresh token. The easiest way is the OAuth 2.0 Playground:
   • Click the gear icon → check Use your own OAuth credentials → paste your client ID and secret (add https://developers.google.com/oauthplayground as an authorized redirect URI to the OAuth client first).
   • In Step 1, enter the scopes https://www.googleapis.com/auth/forms.body https://www.googleapis.com/auth/forms.responses.readonly and click Authorize APIs, signing in with the test-user account.
   • In Step 2, click Exchange authorization code for tokens and copy the refresh token.
5. Put the three values into GOOGLE_FORMS_CLIENT_ID, GOOGLE_FORMS_CLIENT_SECRET and GOOGLE_FORMS_REFRESH_TOKEN. The server exchanges the refresh token for short-lived access tokens automatically.

Scope notes: forms.body + forms.responses.readonly is the minimal, recommended pair (no broad Drive access). While the consent screen stays in Testing mode, refresh tokens expire after 7 days — publish the app (or keep it Internal in a Workspace domain) for long-lived tokens.

⚠️ The credentials are stored in plain text in your client's config — treat them like a password. The refresh token grants access to your forms until revoked at myaccount.google.com/permissions.

Configuration

* Either the three refresh-flow variables together, or GOOGLE_FORMS_ACCESS_TOKEN.

Documentation

• All tools — full reference with parameters and notes.
• Development — build, tests, smoke check, telemetry.
• Publishing — releasing and MCP-catalog listing.

Support

Questions, ideas, issues — Telegram @gistrec or GitHub issues.

License

MIT — see LICENSE.