# Google Forms MCP [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/A1-x-Tech/mcp-google-forms  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1302  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/google-forms-mcp

## Description
MCP server for the Google Forms API: create forms, manage questions, read responses and watches.

## Tools
Capabilities this server exposes over MCP:

- **auth_status** — Shows whether this server is connected to Google: token presence and source (env variables or a stored in-chat login), expiry, the Google account email, granted vs missing OAuth scopes, where the credentials file lives and where the OAuth client comes from. Makes no network calls and never returns the token itself. Call it first when other tools report the server is not connected.
- **setup_instructions** — Step-by-step checklist for connecting this server to Google: creating a Google Cloud project and a Desktop-app OAuth client, publishing the consent screen (mandatory — Testing-mode refresh tokens die after 7 days), downloading the client JSON and handing its PATH to set_client. Works without any credentials; the checklist shortens to 'enable the API + log in' when an OAuth client is already configured (one client serves the whole mcp-google-* line). Never asks the user to paste secrets into the chat.
- **set_client** — Saves the OAuth client credentials from the JSON file downloaded from Google Cloud Console ('Download JSON' on a Desktop-app client). Pass the file PATH — the secret must never be pasted into the chat. The client is stored once in the shared ~/.config/mcp-google-auth/client.json (owner-only) and reused by every mcp-google-* server; tokens stay per-server. After this, call start_login.
- **start_login** — First step of connecting from the chat, without editing config files or restarting the client. Returns authorizeUrl — show it to the user as a clickable link and ask them to open it in the browser ON THIS MACHINE, pick the Google account and approve access. A one-shot listener on 127.0.0.1 catches Google's redirect; the code is exchanged locally and never passes through the chat. Does not open the browser itself. The attempt lives 10 minutes; when the browser shows the success page, call finish_login.
- **finish_login** — Second step: confirms the browser consent finished, saves the tokens to an owner-only file and verifies the login with a read-only identity call, returning the account email and the granted scopes. After success every tool works immediately — no client restart. If the user granted only part of the requested permissions, the login is still saved and missingScopes lists what will not work. Logging in under a different Google account replaces the previous login (its refresh token is revoked best-effort) and the response carries previousAccountEmail so the change never goes unnoticed.
- **logout** — Revokes the stored token at Google (oauth2.googleapis.com/revoke) and deletes the local credentials file. Tokens supplied via env variables are NOT touched — remove them from the MCP client config manually; envTokenStillSet in the response says whether any are still in effect.
- **create_form** — Creates a new Google Form and returns it (formId, revisionId, responderUri, publishSettings). The API only accepts a title and an optional document title at creation (the Drive file name — it cannot be changed later through this API) — add questions with add_question and change settings with update_form_settings afterwards. IMPORTANT: API-created forms are UNPUBLISHED by default and do not accept responses; pass publish=true to publish immediately, or call set_publish_settings later. If the chained publish step fails, the form still exists: the result carries formId with published:false and publish_error — finish with set_publish_settings, never create_form again. Share the responderUri with respondents once published.
- **get_form** — Returns the full form: info (title, description), settings (quiz mode, email collection), items[] with their itemId/questionId and question definitions, publishSettings, responderUri and linkedSheetId. Items are returned in order — their 0-based positions are the indexes that update_question, delete_item and move_item address, so call this before mutating items.
- **update_form_info** — Changes the form's title and/or description. Only the provided fields are touched (the updateMask is computed automatically); at least one field is required. The document title (the Drive file name) is set once at create_form and cannot be changed through the Forms API — renaming the file needs the Drive API, which this server does not cover. Returns the batchUpdate replies with the new revisionId.
- **update_form_settings** — Toggles quiz mode (grading with points) and/or the email collection mode. Quiz mode only enables grading — points, correct answers and feedback are set per question afterwards via update_question with the questionItem.question.grading mask (add_question cannot set them). email_collection_type: DO_NOT_COLLECT, VERIFIED (respondent must be signed in; email verified) or RESPONDER_INPUT (respondent types an email). At least one field is required; only the provided fields are touched.
- **set_publish_settings** — Publishes or unpublishes the form and opens/closes response collection. is_accepting_responses defaults to mirroring is_published (publish = start accepting, unpublish = stop). Use is_published=true with is_accepting_responses=false to keep a published form visible but closed. Fails on legacy forms created before the publish model existed — those are managed only in the Forms UI.
- **add_question** — Adds a question to the form (a convenience wrapper over batchUpdate createItem). Types: text (short answer), paragraph (long answer), radio (single choice), checkbox (multiple choice), dropdown, scale (linear scale low..high), date, time, rating (stars/hearts/thumbs). Choice types require options[]. Returns the created itemId and questionId from the batchUpdate replies. index inserts at that 0-based position; omit it to append at the end (costs one extra read to count items). Quiz grading (points, correct answers, feedback) cannot be set here — after adding, use update_question with the questionItem.question.grading mask. File-upload questions cannot be created via the API, and question grids (questionGroupItem) need raw_request with a batchUpdate body.
- **update_question** — Updates an existing item (question or other) via batchUpdate updateItem. The item is addressed by its 0-based index — call get_form first to see current positions and the item's current shape. item is a raw Forms API Item object with the new values; update_mask names the fields to replace, e.g. "title" or "title,questionItem.question.required". Only masked fields change; masking a field the item object leaves unset clears it.
- **delete_item** — Deletes the item at the given 0-based index (question, page break, text block, ...). Deletion shifts every later item one position down — re-check indexes with get_form between successive deletes.
- **move_item** — Moves the item at from_index to to_index (both 0-based, to_index is the position after removal). Use get_form to see the current order first.
- **list_responses** — Lists submitted responses: responseId, createTime, lastSubmittedTime, respondentEmail (only when email collection is on), answers keyed by questionId (map questionId → question via get_form), and totalScore for graded quizzes. submitted_after keeps only responses submitted strictly after that RFC3339 UTC timestamp — the API's only filter; there is no ordering or email filter, do that client-side. Paginate with page_token from nextPageToken. Note: this endpoint has a lower per-minute quota than other reads — poll incrementally with submitted_after rather than re-listing everything. The API is read-only for responses; submitting them programmatically is impossible.
- **get_response** — Fetches a single submission by its responseId (from list_responses): answers keyed by questionId, createTime, lastSubmittedTime, respondentEmail and totalScore when available. Map questionId to the question text via get_form.
- **manage_watches** — Manages Cloud Pub/Sub push-notification watches on a form. action=create needs event_type (RESPONSES = new submissions, SCHEMA = form structure changes) and topic_name; the topic must live in your Cloud project and grant the Pub/Sub Publisher role to forms-notifications@system.gserviceaccount.com. action=list shows your watches; delete and renew need watch_id. Watches expire after 7 days — renew extends 7 days from now and reactivates a SUSPENDED watch. Notifications carry only formId/watchId/eventType attributes (no payload): on RESPONSES call list_responses with submitted_after, on SCHEMA call get_form. Limits: 1 watch per user per form+event type, 20 per Cloud project.
- **raw_request** — Escape hatch to call any Google Forms API v1 path directly, for requests the typed tools don't cover — e.g. a batchUpdate with questionGroupItem grids, writeControl/requiredRevisionId, includeFormInResponse, or several requests at once: path "v1/forms/<formId>:batchUpdate", method POST, body {"requests":[...]}. The path may carry a query string (e.g. "v1/forms/<id>/responses?filter=timestamp%20%3E%202026-08-01T00:00:00Z"). The Bearer token is added automatically; the method defaults to GET.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `GOOGLE_FORMS_CLIENT_ID`, `GOOGLE_FORMS_CLIENT_SECRET`, `GOOGLE_FORMS_REFRESH_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Google Forms MCP does

Google Forms MCP exposes Google Forms operations as MCP tools. It can create forms, inspect their questions and settings, update titles and descriptions, change quiz or email-collection settings, add and edit supported question types, reorder items, delete items, and publish or close response collection.

The server also reads submitted responses and individual response records. Responses include timestamps, answers keyed by question ID, respondent email when collection is enabled, and quiz scores when available. A raw request tool provides access to Google Forms API endpoints that do not have dedicated wrappers.

## How it works

The server communicates with Google through OAuth 2.0 using the Forms API scopes for form content and read-only responses. Authentication can be completed from the conversation: configure a Desktop-app OAuth client, start login, open the returned authorization URL on the same machine, and finish the login. A local listener on `127.0.0.1` receives the redirect, while tokens are stored in an owner-only local file.

Forms created through the API begin unpublished. Publish them explicitly with `create_form` or `set_publish_settings` before sharing the responder URL. Publishing and response collection are separate controls, so a form can remain visible while refusing new submissions.

Form items are addressed by their zero-based positions. Use `get_form` before modifying, deleting, or moving items, and refresh the form after deletions because later positions shift. Response notifications contain identifiers and event metadata rather than response data; after a notification, retrieve new submissions with `list_responses`.

## Setup and configuration

Node.js 20 or newer and a Google account are required. Add the server to an MCP client with the npm package command:

```bash
npx -y mcp-google-forms@latest
```

Create or select a Google Cloud project, enable the Google Forms API, configure the consent screen, and create a Desktop-app OAuth client. Pass the downloaded client JSON file path to `set_client`; do not paste its secret into chat. The shared client configuration is stored under `~/.config/mcp-google-auth/client.json`, while tokens remain specific to this server.

The package can also use `GOOGLE_FORMS_CLIENT_ID`, `GOOGLE_FORMS_CLIENT_SECRET`, and `GOOGLE_FORMS_REFRESH_TOKEN` in an MCP client configuration. `auth_status` reports credential source, account, expiry, and OAuth scopes without returning the token. `logout` revokes locally stored credentials and removes their file, but does not remove environment variables.

## Tools and capabilities

- Inspect authentication state and obtain setup instructions.
- Create forms and read complete form definitions, including items, publication state, responder URL, and linked sheet ID.
- Update form information and settings, including quiz mode and email collection modes.
- Add text, paragraph, radio, checkbox, dropdown, scale, date, time, and rating questions.
- Update, delete, and move form items by index.
- Publish or unpublish forms and open or close response collection.
- List responses incrementally with an RFC3339 `submitted_after` timestamp, paginate results, or fetch one response by ID.
- Create, list, renew, and delete Cloud Pub/Sub watches for response or schema events.
- Send direct Google Forms API requests with `raw_request`.

## Limitations and notes

The Forms API cannot create, edit, or delete submitted responses. File-upload questions cannot be created through the API, and question grids require a raw batch update. The document title, which is the Drive file name, is set during creation and cannot be changed through this server.

Response listing has a lower per-minute quota than other reads, so incremental polling is preferable to repeatedly fetching all responses. Pub/Sub watches expire after seven days, allow one watch per user per form and event type, and are limited to 20 per Cloud project. The notification topic must be in the Google Cloud project and grant publishing permission to Google's Forms notification service account.

Forms created before Google's publication model may not support publication settings. OAuth consent screens left in Testing mode produce refresh tokens that expire after seven days; publishing the consent screen avoids that behavior.

_Full upstream README: https://allmcps.com/mcp/google-forms-mcp/readme_