Google Search Console

The Google Search Console (GSC) integration imports search performance data into MakinForU: clicks, impressions, CTR and average position per page and per query. Once enabled it powers the SEO page in each project (/<organization>/<project>/seo), Search Console insights on page reports, and the gsc_* tools in the MCP server and the AI assistant.

Enabling it is an instance-level setup (this page) plus a per-project connection that any project admin does from the project's settings under "Google Search".

How it works

1. A project admin clicks "Connect Google Search Console" and is sent to Google with the read-only webmasters.readonly scope.
2. Google redirects back to the API with a code. The API exchanges it for an access token and a refresh token and stores both in PostgreSQL, encrypted with ENCRYPTION_KEY.
3. The admin picks which Search Console property to use. A backfill of the last 6 months starts immediately, in 14-day chunks.
4. Every night at 03:00 (worker time zone) the worker re-syncs a rolling 3-day window, because Google finalises data a couple of days late.
5. Data lands in the ClickHouse tables gsc_daily, gsc_pages_daily and gsc_queries_daily. Re-syncs overwrite earlier rows. There is no retention limit.

A few views (keyword cannibalization, page and query detail drill-downs) query Google live from the API and cache the result for 4 hours, so both the API and the worker need the Google credentials and ENCRYPTION_KEY.

Prerequisites

You need a Google Cloud OAuth client. If you already set up Google sign-in, reuse it. The integration uses the same GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. Google sign-in does not have to be enabled; the OAuth client alone is enough.

You also need ENCRYPTION_KEY set on the API and worker. The Docker Compose setup script generates one. Other deployments must create it with openssl rand -hex 32.

Finally, you need the public API_URL of your instance, e.g. https://analytics.example.com/api.

Setup

${API_URL}/gsc/callback

GOOGLE_CLIENT_ID=123456789012-abcdefghijklmnop.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx
GSC_GOOGLE_REDIRECT_URI=https://analytics.example.com/api/gsc/callback
ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Things to know

Each project has at most one Search Console connection. Disconnecting keeps the data already imported into ClickHouse. Reconnecting to a different property overwrites overlapping dates.

The refresh token belongs to the Google user who clicked "Connect". If that person loses access to the property, or leaves the organisation, syncing stops with token_expired and someone else must reconnect.

Rotating ENCRYPTION_KEY breaks existing connections. Stored tokens can no longer be decrypted and every project must reconnect. The same key also protects two-factor secrets and export credentials, so treat it as permanent.

If you restrict the worker with ENABLED_QUEUES, it must include both gsc (sync and backfill jobs) and cron (the nightly trigger). GSC_CONCURRENCY (default 5) controls how many projects sync in parallel.

Search Console allows thousands of requests per site per day. A 6-month backfill makes roughly 40 requests, and the nightly sync makes 3 per project. You are unlikely to hit limits unless you connect hundreds of projects.

Google typically finalises data 2 to 3 days after the fact. MakinForU requests dataState: all, so recent days include preliminary numbers that later syncs correct.

If the connect callback fails, MakinForU redirects to /login?error=...&correlationId=... even though you are still signed in. Navigate back to the project and search the API logs for the correlation ID to see the full error.

Troubleshooting