mcp-google-forms
Summary: This server connects an AI app to Google Forms via OAuth and lets it inspect, build, publish, and monitor forms and read responses.
Connect and manage Google authentication from chat or env tokens, including setup instructions, login status, and logout.
Create forms; inspect form structure, settings, items, publish status, responder URI, and linked sheet.
Update form title, description, quiz mode, email collection, and publish/open-response settings.
Add, update, delete, and move questions/items, including text, paragraph, choice, dropdown, scale, date, time, and rating questions.
Read submitted responses by list or ID, with filtering by submission time and pagination.
Manage Cloud Pub/Sub notification watches for new responses or schema changes.
Make raw Google Forms API requests for cases not covered by typed tools.
Responses are read-only: the server cannot submit, edit, or delete answers; file-upload questions cannot be created.
Provides tools for managing Google Forms end-to-end: creating forms, adding and editing questions, publishing/unpublishing, reading responses, and managing push-notification watches.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-google-forms Create a customer feedback form with a rating question and publish it."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Google Forms MCP
English | Русский
A1 Google Forms MCP lets an AI app build and manage Google Forms in plain language. Create a survey, choose its questions, publish it when ready, read answers and use notifications for new submissions.
It uses the Google Forms API with your Google account. It distinguishes a draft form from a published form and makes the limits of the Forms API explicit instead of implying that every form task is possible.
19 tools. Inspect form structure and responses, create and edit forms and questions, manage publishing, and configure Pub/Sub watches.
Connects from the conversation. Say "connect Google Forms": the server walks you through the OAuth client, catches Google's redirect on
127.0.0.1with PKCE and keeps the tokens itself — no config files, no restart.Publish deliberately. Forms made through the API start unpublished, so they cannot collect responses until you publish them.
Responses stay intact. The API can read responses but cannot create or edit them; the server has no tool that submits answers.
Minimal Google scopes. It uses
forms.bodyandforms.responses.readonly, without broad Drive access.
Start with a read-only question:
Show me yesterday’s responses to the customer feedback form and summarize the free-text answers.
Connect the server · Explore use cases · Open technical documentation
See it work in a minute
You: Show me the questions and response settings of the customer feedback form.
Assistant: Shows the form, its items, whether it is published and whether it accepts responses. Nothing changes.
You: Prepare a required 1–5 rating question called “How was your experience?” after the first question.
Assistant: Shows the target form, position and proposed question, then asks for confirmation before adding it.
You: Confirm.
Assistant: Adds the question to the form. It does not publish or close the form unless you ask separately.
Related MCP server: Google Workspace MCP Server
Contents
Quick start
You need Node.js 20+ and a Google account. Credentials are not required at install time — the server connects from the conversation.
Add the server to your AI app.
Say "connect Google Forms": the assistant walks you through creating the OAuth client and approving access without editing config files.
Ask the read-only question above.
In the app: open Settings → MCP servers, select Add server, choose STDIO, enter the command npx -y mcp-google-forms@latest and environment variables GOOGLE_FORMS_CLIENT_ID, GOOGLE_FORMS_CLIENT_SECRET, GOOGLE_FORMS_REFRESH_TOKEN, then select Save and Restart.
From the command line:
codex mcp add google-forms \
-- npx -y mcp-google-forms@latestcodex mcp listclaude mcp add \
--transport stdio --scope user google-forms \
-- npx -y mcp-google-forms@latestclaude mcp listThe current official path is Settings → Extensions. For a custom desktop extension, open Advanced settings → Extension Developer → Install Extension…, select a .mcpb file and follow the prompts.
This repository currently publishes an npm stdio package and does not contain a .mcpb bundle. For Claude Desktop builds that still support local configuration, use the following JSON stdio configuration as a fallback:
{
"mcpServers": {
"google-forms": {
"command": "npx",
"args": ["-y", "mcp-google-forms@latest"]
}
}
}In those builds, save it to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.
Claude Desktop MCP documentation
Add this to ~/.cursor/mcp.json on macOS/Linux or %USERPROFILE%\.cursor\mcp.json on Windows:
{
"mcpServers": {
"google-forms": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-google-forms@latest"]
}
}
}Run MCP: Open User Configuration and add:
{
"servers": {
"google-forms": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-google-forms@latest"]
}
}
}Check it with MCP: List Servers.
What you can ask it to do
Inspect a survey and its answers
Show this form’s questions, response settings and responder link.
How many answers arrived since Monday? Summarize the free-text feedback.
Show one response by ID.
Build and improve a form
Create an RSVP form with name, meal preference and arrival date.
Add a required rating, dropdown, date, time, choice or text question.
Reorder a question or update a title, description, quiz mode or email collection.
Publish and connect notifications
Publish a prepared form and show its responder URL.
Stop accepting new responses without deleting the form.
Create, renew or remove a Cloud Pub/Sub watch for new submissions.
How a form changes
create_formcreates a form, which starts unpublished by default.Questions are items, identified by their position in the form.
Publishing makes a form available to respondents; closing response collection leaves it published but stops new submissions.
Responses are a separate read-only record. The API cannot submit, edit or delete a respondent’s answer.
File-upload questions cannot be created through the Forms API, although existing file-upload items can be read. Legacy forms created before Google’s publish model may not support publishing settings.
What can change
Operation | What happens | Confirmation boundary |
Read a form and its responses | Reads form structure and submissions | No change |
Create a form | Adds an unpublished form | Changes Google Forms |
Add or move a question | Changes form items | Changes a form |
Update form info, settings or an item | Changes title, settings or a selected question | Changes a form |
Publish, unpublish, open or close responses | Changes who can use the form | Changes a form’s public availability |
Delete an item | Removes a selected question | Destructive |
Manage a Pub/Sub watch | Creates, renews or deletes notification delivery | Potentially destructive |
Raw API request | Can call API methods without a dedicated tool | Potentially destructive |
The AI client controls confirmation prompts. The server marks reads, writes and destructive tools so the client can distinguish an inspection from a live change.
Getting access
Google Forms requires OAuth 2.0; an API key is not enough. There are two ways in, and the first one needs no configuration files.
Connect from the chat (recommended)
Say "connect Google Forms" and the assistant runs the flow with you:
setup_instructionsprints the checklist: create or select a Google Cloud project, enable Google Forms API, configure the consent screen and create a Desktop app OAuth client.Download that client's JSON ("Download JSON") and give the assistant its path —
set_clientstores it owner-only. The secret never goes through the conversation.start_loginreturns a Google consent link. Open it on this machine and approve; the code comes back to a one-shot listener on127.0.0.1(PKCE), never through the chat.finish_loginexchanges the code and saves the tokens to~/.config/mcp-google-forms/credentials.json(mode 0600).
The tokens are re-read on every call, so the connection works immediately — no restart of the AI app. auth_status shows what is connected, logout revokes and deletes it.
Environment variables (CI, unattended installs)
Create or select a Google Cloud project and enable Google Forms API.
Configure the OAuth consent screen and create a Desktop app OAuth client.
Authorize the Google account that owns or can edit the forms. The OAuth 2.0 Playground can obtain the refresh token when Use your own OAuth credentials is enabled.
Request both scopes:
https://www.googleapis.com/auth/forms.body https://www.googleapis.com/auth/forms.responses.readonly
Testing-mode OAuth refresh tokens can expire after seven days. Publish the OAuth app, or use an Internal app in a Workspace domain, when you need long-lived access. Treat the client secret and refresh token as passwords.
Configuration
Every variable is optional — with none of them the server connects from the chat.
Variable | Required | Description |
| No* | OAuth client ID. |
| No* | OAuth client secret. |
| No* | OAuth refresh token. |
| No* | Short-lived alternative to the OAuth trio. |
| No | Fixed loopback port for the in-chat login; useful over SSH port forwarding. |
| No | Google Forms API base URL override. |
| No | Per-request timeout; default |
| No | Temporary-error retries; default |
* Provide either the OAuth trio or an access token.
Data, limits and background work
Requests go to Google Forms. The local server refreshes Google OAuth tokens and calls the Forms API. Its anonymous telemetry contains an installation ID, package version, AI client and platform versions, and tool names — never OAuth tokens, form data, tool arguments or prompts. For each tool call it also sends the outcome and, on failure, an excerpt of the error text with e-mails, addresses, tokens, numbers of 4+ digits and quoted text replaced by
#; a value from your request can appear in it if the error text contains it. SetASKADS_TELEMETRY=0to opt out.Google applies per-minute quotas. The documented limits are 975 reads per project, 450
list_responsescalls and 375 writes. On429, the server uses backoff; reads also retry after network and5xxerrors, while writes are not replayed after an uncertain failure.There is no background polling. The server runs only when called. Pub/Sub watches can notify your own infrastructure about new responses; if your AI app supports scheduled tasks, it can also check responses periodically.
Technical documentation
MCP capability catalog — task-oriented pages for every tool.
Support
Found a bug or need a scenario? Create an issue or write in Telegram.
Available Tools
19 toolsadd_questionAdd a questionA
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.
Inputs: type (required), title (required), form_id (required), low, +13 more.
auth_statusGoogle connection statusARead-onlyIdempotent
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.
Inputs: no named parameters.
create_formCreate a formA
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.
Inputs: title (required), publish, document_title.
delete_itemDelete an itemADestructive
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.
Inputs: index (required), form_id (required).
finish_loginFinish the Google loginAIdempotent
Second step: waits up to 20 s for the browser consent to finish, 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.
Inputs: no named parameters.
get_formGet a formARead-onlyIdempotent
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.
Inputs: form_id (required).
get_responseGet one responseARead-onlyIdempotent
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.
Inputs: form_id (required), response_id (required).
list_responsesList form responsesARead-onlyIdempotent
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.
Inputs: form_id (required), page_size, page_token, submitted_after.
logoutDisconnect from GoogleADestructive
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.
Inputs: no named parameters.
manage_watchesManage push-notification watchesADestructive
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.
Inputs: action (required), form_id (required), watch_id, event_type, +1 more.
move_itemMove an itemA
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.
Inputs: form_id (required), to_index (required), from_index (required).
raw_requestRaw Google Forms API callADestructive
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/:batchUpdate", method POST, body {"requests":[...]}. The path may carry a query string (e.g. "v1/forms//responses?filter=timestamp%20%3E%202026-08-01T00:00:00Z"). The Bearer token is added automatically; the method defaults to GET.
Inputs: path (required), body, method.
set_clientSave the OAuth clientAIdempotent
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.
Inputs: path (required).
set_publish_settingsPublish or unpublish a formADestructiveIdempotent
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.
Inputs: form_id (required), is_published (required), is_accepting_responses.
setup_instructionsSetup instructionsARead-onlyIdempotent
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.
Inputs: no named parameters.
start_loginStart the Google loginAIdempotent
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.
Inputs: no named parameters.
update_form_infoUpdate form infoADestructiveIdempotent
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.
Inputs: form_id (required), title, description.
update_form_settingsUpdate form settingsADestructiveIdempotent
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.
Inputs: form_id (required), is_quiz, email_collection_type.
update_questionUpdate an itemADestructiveIdempotent
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.
Inputs: item (required), index (required), form_id (required), update_mask (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Each tool targets a distinct resource+action: form info vs settings vs publish, item add/update/delete/move, responses, watches, and a clearly scoped escape hatch. The only soft overlaps are the publish flag on create_form versus set_publish_settings (explicitly documented as a fallback chain) and raw_request, which can duplicate any typed call but is framed as a last resort. The six auth tools are stage-specific (status/instructions/client/two login steps/logout) and readable, though an agent could momentarily confuse setup_instructions with auth_status.
The dominant pattern is verb_noun: create_form, get_form, update_form_info, add_question, delete_item, move_item, list_responses, set_client, start_login, finish_login. Deviations are minor: auth_status is noun-first, setup_instructions is a noun phrase, logout and raw_request drop the verb_noun shape. Still highly predictable overall.
19 tools is on the heavy side, but the domain (auth flow, form metadata, item editing, responses, Pub/Sub watches, raw escape hatch) genuinely needs this surface. The six-tool auth block is the largest cost and could arguably be collapsed, but each step is required by the OAuth dance and none is redundant.
Create/read/update covers forms, items, settings, publishing, responses and watches, with raw_request plugging API gaps like question grids and revision control. Real gaps remain: no delete/duplicate form (Drive API out of scope), no file-upload or grid questions without raw_request, and no response mutation (an API limitation). These are workaroundable, so the surface is solid but not exhaustive.
Maintenance
Related MCP Connectors
Forms for AI agents. Build, publish, and read forms and their replies from any MCP client.
Google Forms MCP: create forms and graded quizzes in your Google Drive, then summarize responses.
Build, edit and publish forms and read their responses from your AI assistant.
MCP server for Google Veo AI video generation
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with Google Sheets through natural language, allowing users to create, read, update, and manage spreadsheet data via the Google Sheets API v4.-
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server integrating Google Docs, Sheets, Drive, Gmail, Calendar, and Apps Script APIs, featuring unique Apps Script support for AI-driven automation.9MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for reading, editing, and publishing Google Forms with the official Google Forms API. Enables AI agents to programmatically create, modify, and manage forms and responses.MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to interact with Google Docs, Sheets, and Drive using the user's own Google account.-