gsc-ga4-mcp
Provides read-only access to Google Analytics 4 (GA4), enabling users to run custom reports, list properties, and analyze top pages, traffic sources, landing pages, events, and realtime activity.
Provides read-only access to Google Search Console, allowing users to list verified sites, query search analytics with custom dimensions and filters, view top queries and pages, inspect query-to-page matrices, and check URL index status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gsc-ga4-mcp Find high-impression low-CTR pages for example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gsc-ga4-mcp
A small local MCP server that gives Claude Code read-only access to Google Search Console and GA4, plus a few tools that cross the two datasets.
The problem
SEO work in an AI assistant usually means exporting CSVs from Search Console, exporting more CSVs from GA4, pasting both into a chat, and repeating that every time you want a fresh number. The two datasets also never line up on their own: Search Console knows impressions, clicks and CTR; GA4 knows sessions, engagement and conversions. Answering "which pages get traffic but waste it" means joining them by URL by hand.
Google publishes an official MCP server for Analytics, but it does not cover Search Console. Community Search Console servers exist, but if the data belongs to clients, running a small wrapper you can read end to end beats trusting someone else's.
This server calls the official Google APIs directly, with read-only scopes, from your own machine.
Related MCP server: Google Search Console MCP Server
What it does
Twenty MCP tools over stdio.
Search Console
Tool | Purpose |
| Sites visible to the current credentials |
| Raw |
| Top queries for a date range |
| Top pages for a date range |
| Query × page breakdown |
| Index status of a single URL |
GA4
Tool | Purpose |
| Accounts and property summaries |
| Raw |
| Pages by sessions/views |
| Sessions by source/medium |
| Landing pages with engagement metrics |
| Event counts |
| Last 30 minutes of activity |
Combined analysis
Tool | Purpose |
| One pass over both APIs, grouped into quick wins and rewrites |
| Joins GSC pages to GA4 pages by URL path |
| Ranking but not earning the click |
| Earning the click, losing the visitor |
| Pages whose performance has decayed |
Config
project_mappings and project_lookup read a local file that maps a project or client name to its GSC property and GA4 property, so you can say "cross GSC and GA4 for example.com" instead of remembering properties/123456789.
Stack
Node.js + TypeScript. @modelcontextprotocol/sdk for the server, google-auth-library for auth, zod for tool schemas. No database, no hosted backend, no telemetry — the process runs locally and Claude Code launches it over stdio.
Scopes are read-only and that is the whole permission surface:
https://www.googleapis.com/auth/webmasters.readonlyhttps://www.googleapis.com/auth/analytics.readonly
Credentials live outside the repo, by default in ~/.config/gsc-ga4-mcp/.
Setup
1. Install
git clone https://github.com/YOUR_USER/gsc-ga4-mcp.git
cd gsc-ga4-mcp
npm install
npm run build
mkdir -p ~/.config/gsc-ga4-mcp2. Enable the APIs
In Google Cloud Console, create or pick a project, then enable:
Google Search Console API
Google Analytics Data API
Google Analytics Admin API
3. Create OAuth credentials
Under APIs & Services → OAuth consent screen, configure the consent screen. Use External if the properties you manage are not all in one Google Workspace, and add your own email as a test user while the app is in testing.
Under APIs & Services → Credentials, create an OAuth client ID of type Desktop app, download the JSON, and save it as ~/.config/gsc-ga4-mcp/oauth-client.json.
For client work where you want permissions isolated per account, use a service account instead and add its email to each GSC and GA4 property with read access. Set GOOGLE_AUTH_MODE=service_account and point GOOGLE_SERVICE_ACCOUNT_KEY_FILE at the key.
4. Configure
cp .env.example .env
cp projects.example.json ~/.config/gsc-ga4-mcp/projects.jsonPaths in .env must be absolute — ~ is not expanded.
GOOGLE_AUTH_MODE=oauth
GOOGLE_OAUTH_CREDENTIALS_FILE=/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json
GOOGLE_TOKEN_PATH=/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json
GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:3000/oauth2callback
PROJECTS_CONFIG=/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json
MCP_DEFAULT_GSC_SITE=sc-domain:example.com
MCP_DEFAULT_GA4_PROPERTY=properties/123456789
MAX_ROWS=25000Project mappings (projects.json):
{
"projects": [
{
"name": "My Site",
"client": "Internal",
"domain": "example.com",
"gscSiteUrl": "sc-domain:example.com",
"ga4Property": "properties/123456789",
"notes": "Replace with the real GA4 property ID."
}
]
}5. Authorise
npm run authThe script starts a loopback listener on 127.0.0.1:3000 and prints a Google URL. Open it, approve the read-only scopes, and the token is written to GOOGLE_TOKEN_PATH.
6. Register with Claude Code
claude mcp add google-seo -- node /ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js
claude mcp listOr check a .mcp.json into the project where you want the tools (see .mcp.example.json):
{
"mcpServers": {
"google-seo": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js"],
"env": {
"GOOGLE_AUTH_MODE": "oauth",
"GOOGLE_OAUTH_CREDENTIALS_FILE": "/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json",
"GOOGLE_TOKEN_PATH": "/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json",
"PROJECTS_CONFIG": "/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json",
"MCP_DEFAULT_GSC_SITE": "sc-domain:example.com",
"MCP_DEFAULT_GA4_PROPERTY": "properties/123456789"
}
}
}
}Use the CLI registration when you would rather keep paths and property defaults out of a repo.
Usage with Claude Code
Ask in plain language; Claude picks the tools.
Use gsc_list_sites and ga4_list_properties. Give me a table of the GSC sites
and GA4 properties I can reach.Analyse organic traffic for sc-domain:example.com over the last 90 days using
gsc_top_queries and gsc_top_pages.Cross GSC and GA4 for example.com over the last 90 days. Find pages with high
impressions and low CTR, and rank the opportunities by likely impact.Run seo_opportunity_report and group the output into quick wins, pages that
need a rewrite, and pages that miss search intent.Inspect https://www.example.com/page/ with gsc_url_inspection and tell me
whether Google has it indexed.Operating notes
Keep
.env,token.json,projects.jsonand any service-account key out of version control. The shipped.gitignorealready covers them.Client analytics data is confidential. Do not paste full outputs into tools the client has not approved.
Revoke the token or the service account when an engagement ends.
MAX_ROWScaps response size. Lower it if replies get unwieldy.
Troubleshooting
Claude Code does not see the tools. Run
claude mcp list, then/mcpinside Claude Code.OAuth token errors. Re-run
npm run authand confirmGOOGLE_TOKEN_PATHis an absolute path.access_denied. Add your email as a test user on the OAuth consent screen while the app is in testing.A domain is missing from GSC. The credentials need access to that exact property —
sc-domain:example.comandhttps://www.example.com/are different properties.A GA4 property is missing. The user or service account needs at least Viewer on the account or property.
gsc_url_inspectionfails.inspectionUrlmust sit insidesiteUrl, and URL-prefix properties must end with/.Invalid GA4 metrics. Use the official GA4 dimension and metric names;
runReportrejects anything else.
References
Licence
MIT. See LICENSE.
Available Tools
20 toolscompare_gsc_ga4_pagesC
Join GSC page performance with GA4 landing-page engagement.
Inputs: endDate (required), startDate (required), siteUrl, property, +1 more.
content_refresh_candidatesC
Rank pages that may deserve a content refresh based on GSC opportunity and GA4 engagement.
Inputs: endDate (required), startDate (required), siteUrl, property, +1 more.
find_high_impression_low_ctr_pagesC
Find GSC pages with high impressions and low CTR.
Inputs: endDate (required), startDate (required), maxCtr, siteUrl, +2 more.
find_pages_with_clicks_but_low_engagementC
Find pages with GSC clicks but weak GA4 engagement.
Inputs: endDate (required), startDate (required), siteUrl, property, +3 more.
ga4_eventsC
GA4 events by event name.
Inputs: endDate (required), startDate (required), limit, property.
ga4_landing_pagesD
GA4 landing pages with engagement metrics.
Inputs: endDate (required), startDate (required), limit, property.
ga4_list_propertiesA
List GA4 accounts and property summaries visible to the credentials.
Inputs: no named parameters.
ga4_realtimeD
GA4 realtime active users report.
Inputs: limit, metrics, property, dimensions.
ga4_run_reportC
Run a raw GA4 Data API report.
Inputs: endDate (required), metrics (required), startDate (required), dimensions (required), +3 more.
ga4_top_pagesC
Top GA4 pages by views, users, and sessions.
Inputs: endDate (required), startDate (required), limit, property.
ga4_traffic_sourcesB
GA4 traffic sources by default channel group and source/medium.
Inputs: endDate (required), startDate (required), limit, property.
gsc_list_sitesA
List Google Search Console sites visible to the current credentials.
Inputs: no named parameters.
gsc_query_page_matrixC
GSC query/page matrix for finding page-level keyword opportunities.
Inputs: endDate (required), startDate (required), siteUrl, rowLimit.
gsc_search_analyticsD
Run a raw Search Console Search Analytics query.
Inputs: endDate (required), startDate (required), type, siteUrl, +3 more.
gsc_top_pagesC
Top GSC pages by clicks/impressions.
Inputs: endDate (required), startDate (required), siteUrl, rowLimit.
gsc_top_queriesC
Top GSC queries by clicks/impressions.
Inputs: endDate (required), startDate (required), siteUrl, rowLimit.
gsc_url_inspectionA
Inspect Google index status for a URL under a GSC property.
Inputs: inspectionUrl (required), siteUrl, languageCode.
project_lookupB
Find a local project mapping by project name, client, or domain.
Inputs: nameOrDomain (required).
project_mappingsB
List local domain/client mappings from PROJECTS_CONFIG.
Inputs: no named parameters.
seo_opportunity_reportC
Compact SEO opportunity report combining high-impression/low-CTR and low-engagement candidates.
Inputs: endDate (required), startDate (required), siteUrl, property, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Several tools overlap heavily: gsc_search_analytics is a raw query tool but gsc_top_queries, gsc_top_pages, and gsc_query_page_matrix are just specialized versions of it. Similarly, ga4_run_report overlaps with ga4_top_pages, ga4_traffic_sources, ga4_landing_pages, and ga4_events, while the final four SEO opportunity tools substantially duplicate one another in purpose.
Naming is mostly consistent with service prefixes (gsc_, ga4_) followed by descriptive topic or verb_noun forms like list_sites and run_report. Minor inconsistencies exist, such as project_mappings/project_lookup using a different pattern and the verb-less gsc_search_analytics, but overall the convention is predictable.
20 tools is on the heavier side, but the server intentionally covers two analytics platforms plus cross-platform analysis, so the count is defensible. A few of the derived report tools are redundant enough that the set could be trimmed, but it does not feel bloated beyond reason.
The toolset covers the core read-only SEO workflow well: GSC site listing, raw and curated search analytics, URL inspection, GA4 property/report access, and cross-platform opportunity analysis. Minor gaps exist, such as no GSC sitemap or index-request tools and no GA4 audience or funnel reports, but the raw query tools provide a workaround.
Maintenance
Related MCP Connectors
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
SEO research, Search Console, GA4 and PPC tools for Claude and ChatGPT.
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Read-only Google Search Console and Google Analytics for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to access Google Search Console data including search performance, URL indexation, sitemaps, and built-in SEO analysis tools such as trending queries, cannibalization detection, and traffic drop diagnostics.101 npm10MIT
- AlicenseAqualityBmaintenanceLets you ask Claude questions about your Google Search Console data and get real analysis, not raw API rows. Provides 20 tools for analysis, indexing, and safety.292,162 npm186Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables users to securely connect Claude to their own Google Search Console data, providing custom SEO analyses such as quick wins, content decay, and cannibalization, plus optional BigQuery bulk export, with per-user token scoping and read-only tools.6 npmMIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables users to query Google Search Console data interactively from Claude Desktop and via CLI, providing search analytics, period comparisons, branded split, indexing status, sitemaps, and full CSV exports.-