Skip to main content

​
What You’ll Learn

  • Connecting Google Search Console via OAuth or Service Account
  • Assigning GSC properties to child sites
  • Viewing search performance and sitemap data
  • Managing automatic refreshes and using AI Assistant actions
  • Troubleshooting common connection issues
Integration Add-on - This add-on extends MainWP Dashboard to work with Google Search Console. Your child sites must already have matching Google Search Console properties available in the connected Google account or service account.
The MainWP Google Search Console Add‑on brings your Google Search Console (GSC) data into your MainWP Dashboard so you can review search performance and technical SEO health for all managed WordPress sites in one place. MainWP Google Search Console add-on Dashboard page

​
Use this Add‑on to Monitor

Search Performance
  • Clicks, Impressions, CTR, Avg. Position
  • Top Queries & Pages; breakdowns by Country, Device, and Search Appearance
  • Daily trend chart
Technical SEO Health (Sitemaps)
  • Submitted vs. Indexed per sitemap
  • Status & last processed dates
  • Errors (when reported)
Multi‑Site Management
  • Centralized properties with per‑site drill‑down
  • Integrates with MainWP widgets and Pro Reports
Requirements
  • PHP 8.1 or higher on the MainWP Dashboard (required by Google libraries)
  • PHP BCMath extension enabled on the MainWP Dashboard (used by the report generator)
  • The default WordPress REST API endpoint (/wp-json/) on the MainWP Dashboard must be reachable. The Sign in with Google OAuth flow uses it to pair with the add-on.
  • Your sites must be verified in Google Search Console
  • For JSON Import: Google Search Console API

​
Connect your Google Search Console Account

You can connect GSC in two ways. Use whichever fits your setup (you can use both):

​
Option A: Sign in with Google (OAuth)

  1. In your MainWP Dashboard, go to MainWP > Add-ons > Analytics > Google Search Console, then open the Add Property tab.
  2. Click Sign in with Google and follow the on-screen prompts to complete authorization.
  3. Next, select the GSC properties you want to connect, then click Continue and then Confirm.
  4. Selected properties will appear under Manage Properties and will be available to assign to child sites.
If HTTP basic auth protects your MainWP Dashboard before it has paired with MainWP Bridge, Sign in with Google can fail because MainWP Bridge must be able to reach your Dashboard. If you need to keep HTTP basic auth enabled, use Import JSON File instead.

​
Option B: Connect a Service Account (JSON file)

Step 1 — Enable the required API (Google Cloud Console)
1

Go to https://console.cloud.google.com and (optionally) create a new Project.

Go to https://console.cloud.google.com and (optionally) create a new Project.
2

Open APIs & Services > Enabled APIs & services.

3

Click + Enable APIs and Services, search for and enable the only required API:

Click + Enable APIs and Services, search for and enable the only required API:
  • Google Search Console API\ Google Search Console API in the API Library
Step 2 — Create a Service Account and JSON key Next, we will create a Service Account, which will be added later on to the desired GSC properties.
  1. In APIs & Services, click + Create credentials and select Service Account.
  2. Give it a name then click Done.
  3. Open the new Service Account, go to the KEYS tab.
  4. Click Add Key > Create new key > JSON > Create.
  5. A JSON file will download automatically; you’ll upload it to the add-on later on.
Step 3 — Grant the Service Account access in Google Search Console
1

Go to your Google Search Console dashboard for the relevant account/property.

2

Open Settings > Users and permissions.

3

Click Add user.

4

Copy the Service Account email from your Google Cloud Console (Service Accounts list / Credentials page).

Copy the Service Account email from your Google Cloud Console (Service Accounts list / Credentials page).
5

Paste it in the Email address field, set Permission to Full, and click Add.

Step 4 — Connect the JSON key in MainWP
  1. In your MainWP Dashboard, go to MainWP > Add-ons > Analytics > Google Search Console > Add Property > Import JSON File.
  2. Upload the JSON key and click Connect Account.
  3. Discovered properties will appear under Manage Properties and will be available to assign to child sites.
Notes
  • The account (Google or Service Account) must have access to each property you want to see in MainWP.
  • If you rotate keys or disable the Service Account, you’ll need to upload a new JSON key to re‑establish the connection.
  • This add‑on does not verify sites in GSC or submit sitemaps; it reads your existing data.

​
Assigning a GSC Property to Each Child Site

The add-on can automatically match a property to a child site when the connected property URL or domain matches the child site’s URL.
You can also manually assign a property to a child site by doing the following:
1

Go to MainWP > Sites > Manage Sites.

2

Locate the desired site, click its name, and then open its Settings page.

3

Find the Google Search Console section and select the matching property.

4

Click Save Settings.

If you use the Team Control add-on, the Google Search Console property selection is only shown on a site’s Settings page to users whose role grants access to the Google Search Console add-on. Users without that permission won’t see the property selector and can’t change the assigned property.Site selectors, site-specific data views, and Dashboard widgets also respect each user’s permitted site access.
Refreshing a connection reconciles its available properties with existing site assignments. If an assigned property is no longer available, the mapping becomes stale and its cached data is invalidated. Restore access to the property or select an available property in the site’s settings.

​
Where to View Data

​
Dashboard Widget

Google Search Console widget showing clicks, impressions, CTR, and position A Google Search Console widget can be enabled on the MainWP Operations page. Use the site selector there to switch sites. When you open the add-on from an individual child site, it loads that site’s Google Search Console data directly.
  • KPIs: Total Clicks, Total Impressions, Average CTR, Average Position
  • Interactive performance chart (Clicks, Impressions, CTR, Position)
  • Quick shortcuts to Search Performance and Sitemaps sections

​
Add-on Pages

Go to MainWP > Add-ons > Analytics > Google Search Console and use these tabs:
  • Visitor Data (per‑site):
    • KPI tiles: Total Clicks, Total Impressions, Avg. CTR, Avg. Position
    • Chart with series for Clicks, Impressions, CTR, Position
    • Widgets: Top Queries, Top Pages, Top Performing Countries, Devices, Search Appearance, Dates
    • Sitemaps: Submitted vs. indexed counts by sitemap, indexing rate, last processed dates, error totals
  • Add Property: Connect properties by Sign In with Google or Import JSON File.
  • Manage Properties: Review properties added by Sign In with Google or JSON; actions include Refresh Data, Reconnect Property for disconnected OAuth properties, and Remove Property.
  • Settings: Configure Graphs display interval, Fetch Google Search Console data automatically, Auto fetch GSC data frequency, and on-demand Refresh Data.

​
Settings & Data Refresh

  • Graphs display interval: Select Week or Month for the reporting period.
  • Fetch Google Search Console data automatically: Enable automatic data refreshes.
  • Auto fetch GSC data frequency: Choose every 1, 3, 9, 15, 18, or 24 hours. The default is 9 hours.
  • Save Settings: Apply the reporting period and refresh settings. Changes can invalidate cached reports so they can be regenerated with the new settings.
  • Refresh Data: Request an on-demand refresh. Check the reported outcome; a failed request does not mean fresh data was stored.
Scheduled refreshes skip overlapping runs. The last successful scheduled refresh time advances only when at least one refresh succeeds; it does not mean every site’s data was refreshed. Automatic refreshes also depend on the MainWP Dashboard’s configured cron system running.

​
AI Assistant and Abilities API

Version 6.3 adds ten abilities for MainWP AI Assistant and API clients to inspect connections and properties, manage site assignments and refresh settings, read cached performance summaries, and request refreshes. For example, ask the AI Assistant to show a site’s Google Search Console mapping or cached search performance, review automatic refresh settings, or request a site refresh. Mapping changes, refresh-setting changes, and connection catalog refreshes support a preview before confirmation. Refresh requests run in the background and return a job ID for checking completion. See Google Search Console Abilities for requirements, permissions, request examples, and job-status handling. The ability that reads performance data returns aggregate metrics; it does not include search queries or individual page URLs.

​
GSC data in Pro Reports

If you use MainWP Pro Reports, you can include Google Search Console data in your client reports. For the full list of available tokens, see the Available Pro Reports Tokens article.

​
Troubleshooting

​
JSON connection fails after updating to 6.3

If Refresh Data shows “Data refresh connection fail.” or previously assigned properties disappear from the selector after updating to 6.3, check the stored Service Account JSON file’s permissions. Version 6.3 rejects JSON credential files with permissions for group or other users, including 644 and 755. Earlier versions did not enforce this check. New uploads are saved with 600 permissions, but upgrading to 6.3 does not change the permissions on existing JSON files.
  1. Locate the JSON credential file in your MainWP Dashboard installation, normally under wp-content/uploads/mainwp/google-search-console/.
  2. Set that file’s permissions to 600 (owner read and write). Apply this to the JSON file, not its containing directory. PHP must still be able to read the file; if it cannot, check that the file ownership matches the PHP process user.
  3. Open MainWP > Add-ons > Analytics > Google Search Console > Manage Properties (/wp-admin/admin.php?page=Extensions-Mainwp-Google-Search-Console-Extension&tab=accounts) and click Refresh Data for the JSON connection. Confirm that the refresh succeeds and the properties are available again.
If the property selector is empty, avoid saving a blank property selection while resolving the connection problem. Previously cached charts can remain visible even when a refresh fails. This permission check applies to Service Account JSON connections. It does not apply to Sign in with Google (OAuth) connections.

​
Cannot update wp-config.php automatically

If you see either of these messages:
MainWP Google Search Console could not update wp-config.php automatically.
MainWP Google Search Console could not add its encryption key to wp-config.php.
The add-on could not safely write its encryption key to the MainWP Dashboard site’s wp-config.php file. This is separate from the Google Service Account JSON key. File mode 0644 does not always allow the update: only the file owner has write access, so the update fails when PHP runs as a different user. File or directory ownership and other server security controls can also prevent a safe update. Add the key manually:
1

Back up wp-config.php.

Create a current backup before editing the file.
2

Generate a secure key.

Run this command in your server terminal:
The command returns a 64-character hexadecimal key. Do not use an online key generator.
3

Add the encryption-key definition.

Edit the active wp-config.php file and add the following line before the line that loads wp-settings.php:
Replace PASTE_THE_64_CHARACTER_KEY_HERE with the key generated in the previous step.
4

Save the file and reload MainWP Dashboard.

The warning should clear after the add-on detects the valid key. Do not change or remove the key after it is in use, because existing encrypted credentials may become unavailable.
Do not make wp-config.php world-writable or grant PHP permission to change file ownership. If you cannot edit the file safely through your hosting control panel or server account, ask your hosting provider or server administrator to add the definition.
A file ending in .mainwp-lock may be created while the add-on coordinates an automatic update. It is a lock file, not the cause of the warning and not a replacement for wp-config.php. Add the definition to the active wp-config.php file. If Google Analytics shows a similar warning, follow the instructions in the Google Analytics troubleshooting section and generate a separate key for its constant. “Google OAuth requires the WordPress REST API to be enabled and reachable”
  • The add-on checks whether /wp-json/ on your MainWP Dashboard returns the expected REST API metadata. When the check fails, the add-on shows a red notice on the Add Property, Manage Properties, and Overview screens, and disables the OAuth buttons (Sign in with Google, Continue, Confirm, Verify Now, Reset Now, and Reconnect Property). The Import JSON File flow is unaffected and can still be used.
  • Make sure the default WordPress REST API endpoint at /wp-json/ is not blocked, disabled, filtered, or behind HTTP basic auth on your MainWP Dashboard.
  • See the WordPress REST API troubleshooting guide for steps to restore REST API access.
  • If you need to keep HTTP basic auth or REST API restrictions enabled, use Import JSON File instead.
Sign in with Google shows site secret not found
  • This error has the same root cause as above: the default WordPress REST API endpoint at /wp-json/ is blocked, disabled, filtered, or behind authentication.
  • Make sure your MainWP Dashboard allows access to /wp-json/.
  • If HTTP basic auth protects your MainWP Dashboard, Sign in with Google can fail because MainWP Bridge cannot complete the initial pairing or re-registration check.
  • If you need to keep HTTP basic auth enabled, use Import JSON File instead.
“Your server does not have the PHP BCMath extension enabled”
  • The MainWP Google Search Console add-on requires the PHP BCMath extension on the MainWP Dashboard server to run the background processes used for Pro Reports.
  • Ask your host to enable the bcmath PHP extension. After it is enabled, refresh the add-on page and the notice will clear.
No data available
  • Confirm the site has a GSC property assigned in its Settings page
  • Ensure the Google account or Service Account has access to the property in GSC.
  • Try Refresh Data from the add‑on Settings or Manage Properties tab.
Re-authentication required
  • If you see a red notice about authentication, click Verify Now and sign in again.
Service Account key disabled/rotated
  • Create a new JSON key for the Service Account, then upload it on Add Property to reconnect.