Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Instructions

List a form's responses.

Args:
    user_google_email (str): The user's Google email address. Required.
    form_id (str): The ID of the form.
    page_size (int): Maximum number of responses to return. Defaults to 10.
    page_token (Optional[str]): Token for retrieving next page of results.

Returns:
    str: List of responses with basic details and pagination info.

Implementation Reference

• gforms/forms_tools.py:216-277 (handler)

  The handler function for the 'list_form_responses' tool. It lists responses for a Google Form using the Forms API, handles pagination, formats the output as a string with response details. Registered via @server.tool() decorator, with error handling and auth decorators.

  @server.tool()
  @handle_http_errors("list_form_responses", is_read_only=True, service_type="forms")
  @require_google_service("forms", "forms")
  async def list_form_responses(
      service,
      user_google_email: str,
      form_id: str,
      page_size: int = 10,
      page_token: Optional[str] = None
  ) -> str:
      """
      List a form's responses.
  
      Args:
          user_google_email (str): The user's Google email address. Required.
          form_id (str): The ID of the form.
          page_size (int): Maximum number of responses to return. Defaults to 10.
          page_token (Optional[str]): Token for retrieving next page of results.
  
      Returns:
          str: List of responses with basic details and pagination info.
      """
      logger.info(f"[list_form_responses] Invoked. Email: '{user_google_email}', Form ID: {form_id}")
  
      params = {
          "formId": form_id,
          "pageSize": page_size
      }
      if page_token:
          params["pageToken"] = page_token
  
      responses_result = await asyncio.to_thread(
          service.forms().responses().list(**params).execute
      )
  
      responses = responses_result.get("responses", [])
      next_page_token = responses_result.get("nextPageToken")
  
      if not responses:
          return f"No responses found for form {form_id} for {user_google_email}."
  
      response_details = []
      for i, response in enumerate(responses, 1):
          response_id = response.get("responseId", "Unknown")
          create_time = response.get("createTime", "Unknown")
          last_submitted_time = response.get("lastSubmittedTime", "Unknown")
  
          answers_count = len(response.get("answers", {}))
          response_details.append(
              f"  {i}. Response ID: {response_id} | Created: {create_time} | Last Submitted: {last_submitted_time} | Answers: {answers_count}"
          )
  
      pagination_info = f"\nNext page token: {next_page_token}" if next_page_token else "\nNo more pages."
  
      result = f"""Form Responses for {user_google_email}:
  - Form ID: {form_id}
  - Total responses returned: {len(responses)}
  - Responses:
  {chr(10).join(response_details)}{pagination_info}"""
  
      logger.info(f"Successfully retrieved {len(responses)} responses for {user_google_email}. Form ID: {form_id}")
      return result

• gforms/forms_tools.py:216-216 (registration)

  The @server.tool() decorator registers the list_form_responses function as an MCP tool.

  @server.tool()