google-sheets-mcp

Instructions

Implementation Reference

• gsheet_mcp_server/handler/sheets/create_sheets_handler.py:147-257 (handler)

  Core handler implementing sheet creation logic: validates inputs, retrieves spreadsheet ID, checks duplicates, calls API to create sheets, handles errors, returns JSON response.

  def create_sheets_handler(
      drive_service,
      sheets_service,
      spreadsheet_name: str,
      sheet_names: List[str]
  ) -> str:
      """
      Handler to create new sheets in a Google Spreadsheet.
      
      Args:
          drive_service: Google Drive service
          sheets_service: Google Sheets service
          spreadsheet_name: Name of the spreadsheet
          sheet_names: List of sheet names to create
      
      Returns:
          JSON string with success status and created sheets info
      """
      try:
          # Validate inputs
          if not sheet_names or not isinstance(sheet_names, list):
              return compact_json_response({
                  "success": False,
                  "message": "Sheet names are required and must be a list."
              })
          
          if len(sheet_names) == 0:
              return compact_json_response({
                  "success": False,
                  "message": "At least one sheet name is required."
              })
          
          # Validate each sheet name
          valid_names = []
          invalid_names = []
          
          for name in sheet_names:
              validation = validate_sheet_name(name)
              if validation["valid"]:
                  valid_names.append(validation["cleaned_name"])
              else:
                  invalid_names.append({"name": name, "error": validation["error"]})
          
          if invalid_names:
              error_messages = [f"'{item['name']}': {item['error']}" for item in invalid_names]
              return compact_json_response({
                  "success": False,
                  "message": f"Invalid sheet names: {'; '.join(error_messages)}",
                  "invalid_names": invalid_names
              })
          
          if not valid_names:
              return compact_json_response({
                  "success": False,
                  "message": "No valid sheet names provided."
              })
          
          # Get spreadsheet ID
          spreadsheet_id = get_spreadsheet_id_by_name(drive_service, spreadsheet_name)
          if not spreadsheet_id:
              return compact_json_response({
                  "success": False,
                  "message": f"Spreadsheet '{spreadsheet_name}' not found."
              })
          
          # Check for duplicate names
          duplicate_check = check_duplicate_sheet_names(sheets_service, spreadsheet_id, valid_names)
          if duplicate_check["has_duplicates"]:
              return compact_json_response({
                  "success": False,
                  "message": duplicate_check["error"]
              })
          
          # Create sheets
          try:
              created_sheets = create_sheets(sheets_service, spreadsheet_id, valid_names)
              
              # Prepare response
              response_data = {
                  "success": True,
                  "spreadsheet_name": spreadsheet_name,
                  "created_sheets": valid_names,
                  "sheets_created": len(created_sheets),
                  "message": f"Successfully created {len(created_sheets)} sheet(s) in '{spreadsheet_name}'",
                  "sheet_details": [
                      {
                          "sheet_id": sheet.sheet_id,
                          "title": sheet.title,
                          "index": sheet.index
                      }
                      for sheet in created_sheets
                  ]
              }
              
              return compact_json_response(response_data)
              
          except HttpError as e:
              error_details = e.error_details if hasattr(e, 'error_details') else str(e)
              return compact_json_response({
                  "success": False,
                  "message": f"Failed to create sheets: {error_details}",
                  "error_code": e.resp.status if hasattr(e, 'resp') else None
              })
          
      except Exception as e:
          return compact_json_response({
              "success": False,
              "message": f"Unexpected error: {str(e)}",
              "error_type": type(e).__name__
          })

• gsheet_mcp_server/server.py:167-176 (registration)

  MCP tool registration for 'create_sheets_tool' including input schema via Field annotations and docstring, thin wrapper initializing services and delegating to handler.

  @mcp.tool()
  def create_sheets_tool(
      spreadsheet_name: str = Field(..., description="The name of the Google Spreadsheet"),
      sheet_names: List[str] = Field(..., description="List of sheet names to create as new sheets")
  ) -> str:
      """
      Create new sheets in a Google Spreadsheet.
      """
      sheets_service, drive_service = _get_google_services()
      return create_sheets_handler(drive_service, sheets_service, spreadsheet_name, sheet_names)

• gsheet_mcp_server/server.py:167-176 (schema)

  Input schema defined by Pydantic Field parameters with descriptions for spreadsheet_name and sheet_names.

  @mcp.tool()
  def create_sheets_tool(
      spreadsheet_name: str = Field(..., description="The name of the Google Spreadsheet"),
      sheet_names: List[str] = Field(..., description="List of sheet names to create as new sheets")
  ) -> str:
      """
      Create new sheets in a Google Spreadsheet.
      """
      sheets_service, drive_service = _get_google_services()
      return create_sheets_handler(drive_service, sheets_service, spreadsheet_name, sheet_names)