google-forms-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# Google Forms MCP
+
+MCP server for Google Forms with OAuth token-file auth.
+
+## Breaking Change (v1 auth migration)
+
+`GOOGLE_REFRESH_TOKEN` is no longer used.
+
+Run one-time auth instead:
+
+```bash
+GOOGLE_CLIENT_ID="your-client-id" \
+GOOGLE_CLIENT_SECRET="your-client-secret" \
+npx -y google-forms-mcp auth
+```
+
+This stores the refresh token at `~/.config/google-docs-mcp/token.json` (respects `XDG_CONFIG_HOME`).
+
+## Setup
+
+1. Enable APIs in Google Cloud:
+- Google Forms API
+- Google Drive API
+- Google Docs API
+- Google Sheets API
+
+2. Create OAuth 2.0 credentials (Desktop app).
+3. Run auth command above once.
+4. Add MCP config:
+
+```json
+{
+  "mcpServers": {
+    "google-forms-mcp": {
+      "command": "npx",
+      "args": ["-y", "google-forms-mcp"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your-client-id",
+        "GOOGLE_CLIENT_SECRET": "your-client-secret"
+      },
+      "type": "stdio"
+    }
+  }
+}
+```
+
+## Shared Token with `google-docs-mcp`
+
+This project intentionally shares token storage with `google-docs-mcp` for DRY setup.
+
+`google-forms-mcp auth` requests superset scopes:
+- `forms`
+- `drive`
+- `documents`
+- `spreadsheets`
+
+That keeps one token usable for both MCP servers.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_form` | Create form |
+| `get_form` | Get form details |
+| `list_forms` | List all forms |
+| `update_form` | Update title/description |
+| `delete_form` | Delete form |
+| `add_section` | Add visual divider (no page break) |
+| `add_page` | Add page break (requires Next button) |
+| `add_text_question` | Add text question |
+| `add_multiple_choice_question` | Add radio/checkbox question |
+| `update_question` | Modify question |
+| `delete_question` | Remove question |
+| `get_form_responses` | Get responses |
+
+## Item Order (Critical)
+
+All items are added at index `0`.
+The last item you add appears first in the form.
+
+## Multiple Choice Options
+
+Options support both formats:
+- Simple: `["Option A", "Option B"]`
+- With description: `[{ "label": "Option A", "description": "Details" }]`
+
+Use `multiSelect: true` for checkboxes.
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+import { OAuth2Client, JWT } from 'google-auth-library';
+export declare const SCOPES: readonly ["https://www.googleapis.com/auth/forms", "https://www.googleapis.com/auth/drive", "https://www.googleapis.com/auth/documents", "https://www.googleapis.com/auth/spreadsheets"];
+export declare function getConfigDir(): string;
+export declare function getTokenPath(): string;
+export declare function authorize(): Promise<OAuth2Client | JWT>;
+export declare function runAuthFlow(): Promise<void>;

package/dist/auth.js

@@ -0,0 +1,186 @@
+import { google } from 'googleapis';
+import { JWT } from 'google-auth-library';
+import * as fs from 'fs/promises';
+import * as http from 'http';
+import * as os from 'os';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { logger } from './logger.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRootDir = path.resolve(__dirname, '..');
+const CREDENTIALS_PATH = path.join(projectRootDir, 'credentials.json');
+export const SCOPES = [
+    'https://www.googleapis.com/auth/forms',
+    'https://www.googleapis.com/auth/drive',
+    'https://www.googleapis.com/auth/documents',
+    'https://www.googleapis.com/auth/spreadsheets',
+];
+export function getConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg || path.join(os.homedir(), '.config');
+    return path.join(base, 'google-docs-mcp');
+}
+export function getTokenPath() {
+    return path.join(getConfigDir(), 'token.json');
+}
+async function loadClientSecrets() {
+    const envId = process.env.GOOGLE_CLIENT_ID;
+    const envSecret = process.env.GOOGLE_CLIENT_SECRET;
+    if (envId && envSecret) {
+        return { client_id: envId, client_secret: envSecret };
+    }
+    try {
+        const content = await fs.readFile(CREDENTIALS_PATH, 'utf8');
+        const keys = JSON.parse(content);
+        const key = keys.installed || keys.web;
+        if (!key) {
+            throw new Error('Could not find client secrets in credentials.json.');
+        }
+        return {
+            client_id: key.client_id,
+            client_secret: key.client_secret,
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error('No OAuth credentials found. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET ' +
+                'environment variables, or place a credentials.json file in the project root.');
+        }
+        throw error;
+    }
+}
+async function authorizeWithServiceAccount() {
+    const serviceAccountPath = process.env.SERVICE_ACCOUNT_PATH;
+    const impersonateUser = process.env.GOOGLE_IMPERSONATE_USER;
+    if (!serviceAccountPath) {
+        throw new Error('SERVICE_ACCOUNT_PATH is required for service account authentication.');
+    }
+    try {
+        const keyFileContent = await fs.readFile(serviceAccountPath, 'utf8');
+        const serviceAccountKey = JSON.parse(keyFileContent);
+        const auth = new JWT({
+            email: serviceAccountKey.client_email,
+            key: serviceAccountKey.private_key,
+            scopes: [...SCOPES],
+            subject: impersonateUser,
+        });
+        await auth.authorize();
+        if (impersonateUser) {
+            logger.info(`Service Account authentication successful, impersonating: ${impersonateUser}`);
+        }
+        else {
+            logger.info('Service Account authentication successful!');
+        }
+        return auth;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            logger.error(`FATAL: Service account key file not found at path: ${serviceAccountPath}`);
+            throw new Error('Service account key file not found. Please check the path in SERVICE_ACCOUNT_PATH.');
+        }
+        logger.error('FATAL: Error loading or authorizing the service account key:', error.message);
+        throw new Error('Failed to authorize using the service account. Ensure the key file is valid and the path is correct.');
+    }
+}
+async function loadSavedCredentialsIfExist() {
+    try {
+        const tokenPath = getTokenPath();
+        const content = await fs.readFile(tokenPath, 'utf8');
+        const credentials = JSON.parse(content);
+        const { client_secret, client_id } = await loadClientSecrets();
+        const client = new google.auth.OAuth2(client_id, client_secret);
+        client.setCredentials(credentials);
+        return client;
+    }
+    catch {
+        return null;
+    }
+}
+async function saveCredentials(client) {
+    if (!client.credentials.refresh_token) {
+        throw new Error('No refresh token received. Run auth again and ensure consent is granted.');
+    }
+    const { client_secret, client_id } = await loadClientSecrets();
+    const configDir = getConfigDir();
+    await fs.mkdir(configDir, { recursive: true });
+    const payload = JSON.stringify({
+        type: 'authorized_user',
+        client_id,
+        client_secret,
+        refresh_token: client.credentials.refresh_token,
+    }, null, 2);
+    const tokenPath = getTokenPath();
+    await fs.writeFile(tokenPath, payload);
+    logger.info(`Token stored to ${tokenPath}`);
+}
+async function authenticate() {
+    const { client_secret, client_id } = await loadClientSecrets();
+    const server = http.createServer();
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        server.close();
+        throw new Error('Failed to start OAuth callback server.');
+    }
+    const redirectUri = `http://127.0.0.1:${address.port}`;
+    const oauthClient = new google.auth.OAuth2(client_id, client_secret, redirectUri);
+    const authorizeUrl = oauthClient.generateAuthUrl({
+        access_type: 'offline',
+        prompt: 'consent',
+        scope: SCOPES.join(' '),
+    });
+    logger.info('Authorize this app by visiting this URL:');
+    logger.info(authorizeUrl);
+    const code = await new Promise((resolve, reject) => {
+        server.on('request', (req, res) => {
+            const reqUrl = req.url;
+            if (!reqUrl) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<h1>Invalid request</h1><p>You can close this tab.</p>');
+                return;
+            }
+            const url = new URL(reqUrl, redirectUri);
+            const authCode = url.searchParams.get('code');
+            const error = url.searchParams.get('error');
+            if (error) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<h1>Authorization failed</h1><p>You can close this tab.</p>');
+                reject(new Error(`Authorization error: ${error}`));
+                server.close();
+                return;
+            }
+            if (!authCode) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<h1>No code found</h1><p>You can close this tab.</p>');
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end('<h1>Authorization successful!</h1><p>You can close this tab.</p>');
+            resolve(authCode);
+            server.close();
+        });
+    });
+    const { tokens } = await oauthClient.getToken(code);
+    oauthClient.setCredentials(tokens);
+    await saveCredentials(oauthClient);
+    logger.info('Authentication successful!');
+    return oauthClient;
+}
+export async function authorize() {
+    if (process.env.SERVICE_ACCOUNT_PATH) {
+        logger.info('Service account path detected. Attempting service account authentication...');
+        return authorizeWithServiceAccount();
+    }
+    logger.info('Attempting OAuth 2.0 authentication...');
+    const client = await loadSavedCredentialsIfExist();
+    if (client) {
+        logger.info('Using saved credentials.');
+        return client;
+    }
+    logger.info('No saved token found. Starting interactive authentication flow...');
+    return authenticate();
+}
+export async function runAuthFlow() {
+    await authenticate();
+}

package/dist/clients.d.ts

@@ -0,0 +1,9 @@
+import { drive_v3, forms_v1 } from 'googleapis';
+import { OAuth2Client, JWT } from 'google-auth-library';
+export declare function initializeGoogleClient(): Promise<{
+    authClient: JWT | OAuth2Client | null;
+    googleForms: forms_v1.Forms;
+    googleDrive: drive_v3.Drive;
+}>;
+export declare function getFormsClient(): Promise<forms_v1.Forms>;
+export declare function getDriveClient(): Promise<drive_v3.Drive>;

package/dist/clients.js

@@ -0,0 +1,53 @@
+import { google } from 'googleapis';
+import { UserError } from 'fastmcp';
+import { authorize } from './auth.js';
+import { logger } from './logger.js';
+let authClient = null;
+let googleForms = null;
+let googleDrive = null;
+export async function initializeGoogleClient() {
+    if (googleForms && googleDrive) {
+        return { authClient, googleForms, googleDrive };
+    }
+    if (!authClient) {
+        try {
+            logger.info('Attempting to authorize Google API client...');
+            const client = await authorize();
+            authClient = client;
+            googleForms = google.forms({ version: 'v1', auth: authClient });
+            googleDrive = google.drive({ version: 'v3', auth: authClient });
+            logger.info('Google API client authorized successfully.');
+        }
+        catch (error) {
+            logger.error('FATAL: Failed to initialize Google API client:', error);
+            authClient = null;
+            googleForms = null;
+            googleDrive = null;
+            throw new Error('Google client initialization failed. Cannot start server tools.');
+        }
+    }
+    if (authClient && !googleForms) {
+        googleForms = google.forms({ version: 'v1', auth: authClient });
+    }
+    if (authClient && !googleDrive) {
+        googleDrive = google.drive({ version: 'v3', auth: authClient });
+    }
+    if (!googleForms || !googleDrive) {
+        throw new Error('Google Forms and Drive clients could not be initialized.');
+    }
+    return { authClient, googleForms, googleDrive };
+}
+export async function getFormsClient() {
+    const { googleForms: forms } = await initializeGoogleClient();
+    if (!forms) {
+        throw new UserError('Google Forms client is not initialized. Authentication may have failed during startup.');
+    }
+    return forms;
+}
+export async function getDriveClient() {
+    const { googleDrive: drive } = await initializeGoogleClient();
+    if (!drive) {
+        throw new UserError('Google Drive client is not initialized. Authentication may have failed during startup.');
+    }
+    return drive;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { FastMCP } from 'fastmcp';
+import { initializeGoogleClient } from './clients.js';
+import { logger } from './logger.js';
+import { registerAllTools } from './tools/index.js';
+if (process.argv[2] === 'auth') {
+    const { runAuthFlow } = await import('./auth.js');
+    try {
+        await runAuthFlow();
+        logger.info('Authorization complete. You can now start the MCP server.');
+        process.exit(0);
+    }
+    catch (error) {
+        logger.error('Authorization failed:', error?.message || error);
+        process.exit(1);
+    }
+}
+process.on('uncaughtException', (error) => {
+    logger.error('Uncaught Exception:', error);
+});
+process.on('unhandledRejection', (reason) => {
+    logger.error('Unhandled Promise Rejection:', reason);
+});
+const server = new FastMCP({
+    name: 'Google Forms MCP Server',
+    version: '1.0.0',
+});
+registerAllTools(server);
+try {
+    await initializeGoogleClient();
+    logger.info('Starting Google Forms MCP server...');
+    server.start({ transportType: 'stdio' });
+    logger.info('MCP server running using stdio. Awaiting client connection...');
+}
+catch (startError) {
+    logger.error('FATAL: Server failed to start:', startError?.message || startError);
+    process.exit(1);
+}

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+export declare function refreshLogLevel(): void;
+export declare const logger: {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+};

package/dist/logger.js

@@ -0,0 +1,43 @@
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+function resolveLevel() {
+    const env = process.env.LOG_LEVEL?.toLowerCase();
+    if (env && env in LOG_LEVELS) {
+        return env;
+    }
+    return 'info';
+}
+let currentLevel = resolveLevel();
+export function refreshLogLevel() {
+    currentLevel = resolveLevel();
+}
+function shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+export const logger = {
+    debug(...args) {
+        if (shouldLog('debug')) {
+            console.error('[DEBUG]', ...args);
+        }
+    },
+    info(...args) {
+        if (shouldLog('info')) {
+            console.error('[INFO]', ...args);
+        }
+    },
+    warn(...args) {
+        if (shouldLog('warn')) {
+            console.error('[WARN]', ...args);
+        }
+    },
+    error(...args) {
+        if (shouldLog('error')) {
+            console.error('[ERROR]', ...args);
+        }
+    },
+};

package/dist/tools/forms.d.ts

@@ -0,0 +1,16 @@
+import type { FastMCP } from 'fastmcp';
+import { forms_v1 } from 'googleapis';
+import { z } from 'zod';
+export declare const OptionSchema: z.ZodUnion<[z.ZodString, z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    description?: string | undefined;
+}, {
+    label: string;
+    description?: string | undefined;
+}>]>;
+export type FormChoice = z.infer<typeof OptionSchema>;
+export declare function formatOptions(options: FormChoice[]): forms_v1.Schema$Option[];
+export declare function registerFormsTools(server: FastMCP): void;

package/dist/tools/forms.js

@@ -0,0 +1,365 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient, getFormsClient } from '../clients.js';
+export const OptionSchema = z.union([
+    z.string(),
+    z.object({
+        label: z.string(),
+        description: z.string().optional(),
+    }),
+]);
+export function formatOptions(options) {
+    return options.map((opt) => {
+        if (typeof opt === 'string') {
+            return { value: opt };
+        }
+        const value = opt.description ? `${opt.label} – ${opt.description}` : opt.label;
+        return { value };
+    });
+}
+function jsonResponse(data) {
+    return JSON.stringify(data, null, 2);
+}
+export function registerFormsTools(server) {
+    server.addTool({
+        name: 'create_form',
+        description: 'Create a new Google Form',
+        parameters: z.object({
+            title: z.string().describe('Form title'),
+            description: z.string().optional().describe('Form description'),
+        }),
+        execute: async ({ title, description }) => {
+            const forms = await getFormsClient();
+            const res = await forms.forms.create({
+                requestBody: {
+                    info: { title, documentTitle: title, description },
+                },
+            });
+            const formId = res.data.formId;
+            return jsonResponse({
+                formId,
+                title,
+                description: description || '',
+                responderUri: `https://docs.google.com/forms/d/${formId}/viewform`,
+            });
+        },
+    });
+    server.addTool({
+        name: 'get_form',
+        description: 'Get form details',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+        }),
+        execute: async ({ formId }) => {
+            const forms = await getFormsClient();
+            const res = await forms.forms.get({ formId });
+            return jsonResponse(res.data);
+        },
+    });
+    server.addTool({
+        name: 'list_forms',
+        description: 'List all Google Forms',
+        parameters: z.object({
+            limit: z.number().optional().default(10).describe('Max forms to return'),
+        }),
+        execute: async ({ limit }) => {
+            const drive = await getDriveClient();
+            const res = await drive.files.list({
+                q: "mimeType='application/vnd.google-apps.form'",
+                pageSize: limit,
+                fields: 'files(id, name, createdTime, modifiedTime, webViewLink)',
+                orderBy: 'modifiedTime desc',
+            });
+            const result = (res.data.files || []).map((file) => ({
+                formId: file.id,
+                title: file.name,
+                createdTime: file.createdTime,
+                modifiedTime: file.modifiedTime,
+                editUrl: file.webViewLink,
+                responderUrl: `https://docs.google.com/forms/d/e/${file.id}/viewform`,
+            }));
+            return jsonResponse({ count: result.length, forms: result });
+        },
+    });
+    server.addTool({
+        name: 'update_form',
+        description: 'Update form title and/or description',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+            title: z.string().optional().describe('New title'),
+            description: z.string().optional().describe('New description'),
+        }),
+        execute: async ({ formId, title, description }) => {
+            if (!title && description === undefined) {
+                throw new UserError('At least title or description is required');
+            }
+            const forms = await getFormsClient();
+            const updateFormInfo = {};
+            const updateMask = [];
+            if (title) {
+                updateFormInfo.title = title;
+                updateMask.push('title');
+            }
+            if (description !== undefined) {
+                updateFormInfo.description = description;
+                updateMask.push('description');
+            }
+            await forms.forms.batchUpdate({
+                formId,
+                requestBody: {
+                    requests: [{ updateFormInfo: { info: updateFormInfo, updateMask: updateMask.join(',') } }],
+                },
+            });
+            return jsonResponse({ success: true, message: 'Form updated', title, description });
+        },
+    });
+    server.addTool({
+        name: 'delete_form',
+        description: 'Delete a Google Form permanently',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+        }),
+        execute: async ({ formId }) => {
+            const drive = await getDriveClient();
+            await drive.files.delete({ fileId: formId });
+            return jsonResponse({ success: true, message: `Form ${formId} deleted` });
+        },
+    });
+    server.addTool({
+        name: 'add_section',
+        description: 'Add a section header/divider (no page break, single page)',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+            title: z.string().describe('Header title'),
+            description: z.string().optional().describe('Header description'),
+        }),
+        execute: async ({ formId, title, description }) => {
+            const forms = await getFormsClient();
+            const item = {
+                title,
+                textItem: {},
+            };
+            if (description) {
+                item.description = description;
+            }
+            await forms.forms.batchUpdate({
+                formId,
+                requestBody: {
+                    requests: [{ createItem: { item, location: { index: 0 } } }],
+                },
+            });
+            return jsonResponse({ success: true, message: 'Section added', title, description });
+        },
+    });
+    server.addTool({
+        name: 'add_page',
+        description: 'Add a page break (requires clicking Next to continue)',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+            title: z.string().describe('Section title'),
+            description: z.string().optional().describe('Section description'),
+        }),
+        execute: async ({ formId, title, description }) => {
+            const forms = await getFormsClient();
+            const item = {
+                title,
+                pageBreakItem: {},
+            };
+            if (description) {
+                item.description = description;
+            }
+            await forms.forms.batchUpdate({
+                formId,
+                requestBody: {
+                    requests: [{ createItem: { item, location: { index: 0 } } }],
+                },
+            });
+            return jsonResponse({ success: true, message: 'Page added', title, description });
+        },
+    });
+    server.addTool({
+        name: 'add_text_question',
+        description: 'Add a text question to the form',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+            question: z.string().describe('Question title'),
+            description: z.string().optional().describe('Help text'),
+            required: z.boolean().optional().default(false).describe('Required?'),
+        }),
+        execute: async ({ formId, question, description, required }) => {
+            const forms = await getFormsClient();
+            const item = {
+                title: question,
+                questionItem: {
+                    question: {
+                        required,
+                        textQuestion: {},
+                    },
+                },
+            };
+            if (description) {
+                item.description = description;
+            }
+            await forms.forms.batchUpdate({
+                formId,
+                requestBody: {
+                    requests: [{ createItem: { item, location: { index: 0 } } }],
+                },
+            });
+            return jsonResponse({ success: true, message: 'Text question added', question, required });
+        },
+    });
+    server.addTool({
+        name: 'add_multiple_choice_question',
+        description: 'Add a multiple choice question to the form',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+            question: z.string().describe('Question title'),
+            options: z.array(OptionSchema).describe('Choices (string or {label, description})'),
+            required: z.boolean().optional().default(false).describe('Required?'),
+            includeOther: z.boolean().optional().default(true).describe('Add "Other" option'),
+            multiSelect: z.boolean().optional().default(false).describe('Allow multiple selections (checkboxes)'),
+        }),
+        execute: async ({ formId, question, options, required, includeOther, multiSelect }) => {
+            const forms = await getFormsClient();
+            const choices = formatOptions(options);
+            if (includeOther) {
+                choices.push({ isOther: true });
+            }
+            const item = {
+                title: question,
+                questionItem: {
+                    question: {
+                        required,
+                        choiceQuestion: {
+                            type: multiSelect ? 'CHECKBOX' : 'RADIO',
+                            options: choices,
+                        },
+                    },
+                },
+            };
+            await forms.forms.batchUpdate({
+                formId,
+                requestBody: {
+                    requests: [{ createItem: { item, location: { index: 0 } } }],
+                },
+            });
+            return jsonResponse({
+                success: true,
+                message: 'Multiple choice question added',
+                question,
+                options,
+                required,
+            });
+        },
+    });
+    server.addTool({
+        name: 'update_question',
+        description: 'Update an existing question',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+            index: z.number().describe('Question index (0-based)'),
+            question: z.string().optional().describe('New title'),
+            description: z.string().optional().describe('New description'),
+            options: z.array(OptionSchema).optional().describe('New options (for choice questions)'),
+            required: z.boolean().optional().describe('Required?'),
+        }),
+        execute: async ({ formId, index, question, description, options, required }) => {
+            const forms = await getFormsClient();
+            const form = await forms.forms.get({ formId });
+            const items = form.data.items || [];
+            if (index < 0 || index >= items.length) {
+                throw new UserError(`Invalid index: ${index}. Form has ${items.length} items.`);
+            }
+            const existingItem = items[index];
+            if (!existingItem?.itemId) {
+                throw new UserError(`Item at index ${index} is missing an itemId.`);
+            }
+            const updateMask = [];
+            const item = {};
+            if (question !== undefined) {
+                item.title = question;
+                updateMask.push('title');
+            }
+            if (description !== undefined) {
+                item.description = description;
+                updateMask.push('description');
+            }
+            if (existingItem.questionItem) {
+                item.questionItem = { question: {} };
+                if (required !== undefined) {
+                    item.questionItem.question = { required };
+                    updateMask.push('questionItem.question.required');
+                }
+                if (options && existingItem.questionItem.question?.choiceQuestion) {
+                    const choices = formatOptions(options);
+                    item.questionItem.question = {
+                        ...item.questionItem.question,
+                        choiceQuestion: {
+                            ...existingItem.questionItem.question.choiceQuestion,
+                            options: choices,
+                        },
+                    };
+                    updateMask.push('questionItem.question.choiceQuestion.options');
+                }
+            }
+            if (updateMask.length === 0) {
+                throw new UserError('At least one field to update is required');
+            }
+            await forms.forms.batchUpdate({
+                formId,
+                requestBody: {
+                    requests: [
+                        {
+                            updateItem: {
+                                item: { itemId: existingItem.itemId, ...item },
+                                location: { index },
+                                updateMask: updateMask.join(','),
+                            },
+                        },
+                    ],
+                },
+            });
+            return jsonResponse({
+                success: true,
+                message: `Question at index ${index} updated`,
+                updated: updateMask,
+            });
+        },
+    });
+    server.addTool({
+        name: 'delete_question',
+        description: 'Delete a question from the form by index',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+            index: z.number().describe('Question index (0-based)'),
+        }),
+        execute: async ({ formId, index }) => {
+            const forms = await getFormsClient();
+            const form = await forms.forms.get({ formId });
+            const items = form.data.items || [];
+            if (index < 0 || index >= items.length) {
+                throw new UserError(`Invalid index: ${index}. Form has ${items.length} items.`);
+            }
+            await forms.forms.batchUpdate({
+                formId,
+                requestBody: {
+                    requests: [{ deleteItem: { location: { index } } }],
+                },
+            });
+            return jsonResponse({ success: true, message: `Question at index ${index} deleted` });
+        },
+    });
+    server.addTool({
+        name: 'get_form_responses',
+        description: 'Get form responses',
+        parameters: z.object({
+            formId: z.string().describe('Form ID'),
+        }),
+        execute: async ({ formId }) => {
+            const forms = await getFormsClient();
+            const res = await forms.forms.responses.list({ formId });
+            return jsonResponse(res.data);
+        },
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+import type { FastMCP } from 'fastmcp';
+export declare function registerAllTools(server: FastMCP): void;

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+import { registerFormsTools } from './forms.js';
+export function registerAllTools(server) {
+    registerFormsTools(server);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "google-forms-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Google Forms",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "google-forms-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node ./dist/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "fastmcp": "^3.24.0",
+    "google-auth-library": "^10.5.0",
+    "googleapis": "^171.4.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18"
+  }
+}