barie-google-forms-mcp 0.1.2

Google Forms MCP Server for managing forms and responses via the Model Context Protocol

Google Forms MCP Server

An MCP server for managing Google Forms and form responses, integrating seamlessly with AI assistants using the Model Context Protocol.

Features

• List Forms: Search and list Google Forms from Drive with optional title filter and pagination.
• Get Form: Retrieve metadata, items, and settings for a specific form.
• Create Form: Create a new, empty Google Form by title.
• Batch Update: Add, move, or delete items and update form info via the Forms batchUpdate API.
• List Responses: Page through responses for a form, with optional time filter.
• Get Response: Fetch a single response by responseId.
• Manage Watches: Create, list, and delete Pub/Sub watches for SCHEMA or RESPONSES events.

Installation

Prerequisites

• Python 3.9 or higher.
• A Google Cloud Project with the Google Forms API and Google Drive API enabled.
• OAuth2 credentials (Client ID and Client Secret).
• OAuth scopes (defaults, used if --scopes not provided):
  • https://www.googleapis.com/auth/forms.body — read/write form structure
  • https://www.googleapis.com/auth/forms.responses.readonly — read form responses
  • https://www.googleapis.com/auth/drive.readonly — list forms via Drive

The server's list_forms tool calls the Drive API, and list_responses / get_response call the Forms responses endpoint, so all three scopes are needed for full functionality.

Local Setup

1. Install dependencies:

   pip install -e .
   

   The published wheel contains server.py, schemas.py, and tools/ — not main.py (see below).

2. Run the server:

   python server.py \
     --access-token <ACCESS_TOKEN> \
     --refresh-token <REFRESH_TOKEN> \
     --client-id <CLIENT_ID> \
     --client-secret <CLIENT_SECRET>
   

   Optional flags:

   • --expiry <ISO_TIMESTAMP> — token expiry (e.g. 2026-05-07T12:00:00Z).
   • --scopes '["https://www.googleapis.com/auth/forms.body","https://www.googleapis.com/auth/forms.responses.readonly","https://www.googleapis.com/auth/drive.readonly"]' — JSON array of scopes.
   • --log-level DEBUG|INFO|WARNING|ERROR — log verbosity (defaults to INFO).

   Environment variable fallbacks (used when the matching CLI flag is absent):

   • GOOGLE_ACCESS_TOKEN, GOOGLE_REFRESH_TOKEN, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
   • GOOGLE_TOKEN_EXPIRY, GOOGLE_SCOPES, LOG_LEVEL

Configuration

Add the following to your MCP host configuration (e.g., mcp-config.json):

{
  "mcpServers": {
    "barie-google-forms-mcp": {
      "command": "uvx",
      "args": [
        "barie-google-forms-mcp",
        "--access-token",
        "YOUR_ACCESS_TOKEN",
        "--refresh-token",
        "YOUR_REFRESH_TOKEN",
        "--client-id",
        "YOUR_CLIENT_ID",
        "--client-secret",
        "YOUR_CLIENT_SECRET"
      ]
    }
  }
}

For local development against the source tree, use uvx --from /path/to/google_forms barie-google-forms-mcp ... instead.

Optional: main.py (Barie monorepo only)

main.py is not shipped in the PyPI wheel. It wires this MCP server into CAMEL-AI (camel.toolkits) and Barie’s mcp_use_service. If you run it from a full monorepo checkout:

pip install -e ".[internal]"   # pulls python-dotenv; you still need camel-ai + Barie services on PYTHONPATH

If imports are missing, you will get an explicit ImportError telling you to use barie-google-forms-mcp / python server.py instead.

Publishing (maintainers)

From this directory:

rm -rf dist/ build/ *.egg-info
python -m build
python -m twine check dist/*
# TestPyPI first (recommended):
# python -m twine upload --repository testpypi dist/*

Tools

• list_forms: List Google Forms from Drive (optional query, pageSize, pageToken).
• get_form: Get form metadata, items, and settings by formId.
• create_form: Create a new, empty form with a title.
• batch_update_form: Apply a list of requests (e.g. createItem, updateFormInfo) to a form.
• list_responses: List responses for a form, with optional filter, pageSize, and pageToken.
• get_response: Get a single response by formId and responseId.
• create_watch: Create a Pub/Sub watch on a form (eventType: SCHEMA or RESPONSES).
• list_watches: List all watches for a form.
• delete_watch: Delete a watch by formId and watchId.

Watch Tool Notes

create_watch requires a Google Cloud Pub/Sub topic and proper IAM bindings. Example payload:

{
  "formId": "FORM_ID",
  "target": { "topic": { "topicName": "projects/PROJECT/topics/TOPIC" } },
  "eventType": "RESPONSES"
}

Allowed eventType values: SCHEMA, RESPONSES.

Reliability

• Transient Google API errors (HTTP 429/500/502/503/504) are automatically retried up to 3 times with exponential backoff via tenacity.
• All Google API calls are dispatched off the asyncio event loop with asyncio.to_thread so the MCP server stays responsive.
• HttpErrors are surfaced as {"error": "Google API error <status>: <message>"} instead of leaking internal tracebacks.

License

MIT