gsc-mcp
AGENTS.md7 starsChanged 3 months agoMITView on GitHub
For an AI agent working with this repository. This is a local Google Search Console MCP server: one Go binary over stdio, using the user's own Google account to query Search Console properties they are already allowed to access. Choose the right path first: Do not improvise an order, and do not jump from the binary to OAuth. Every command below is executed by you, the agent, through your terminal tool. The user's only task is choosing a Google account…
- Pipes a download into a shell
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository7 other files it gives its agents.
- .cursor/rules/gsc-mcp.mdcCursor rule
- ctr-gapsSkill
- gsc-recipesSkill
- index-healthSkill
- monthly-reportSkill
- nonbrand-performanceSkill
- traffic-decline-diagnosisSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
16 rules. About 0 are common, 4 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Do not improvise an order, and do not jump from the binary to OAuth.
- Very specific: line 84
Run gsc-mcp setup, finish the selected client's configuration, restart that client or open a new session, and verify its MCP server list …
- Very specific: line 86
Only then call list_sites.
- Very specific: line 89
If any command fails, run gsc-mcp doctor again and read its output before changing anything: it runs every check plus one real list_sites …
- Distinctive: line 97
Before starting OAuth, tell the user that a Google sign-in page will open and that their only task is to choose an account and approve …
- Distinctive: line 102
Keep that command running while the user completes Google's browser UI.
- Very specific: line 132
Downloading a Windows executable manually: Use install.ps1: a manual download skips SHA-256 verification and SmartScreen unblocking and …
- Very specific: line 135
Printing credential contents: Use ls only to confirm a file exists.
- Distinctive: line 137
Stopping after printing an OAuth command: Keep the terminal process alive, wait for browser consent, then continue automatically from …
- Very specific: line 140
Assuming a running client hot-loads MCP configuration: Verify the server list, then restart or open a new session before calling list_sites.
- Very specific: line 190
Always read truncated and scan_capped.
- Very specific: line 196
Every compare_periods delta is B minus A.
- Very specific: line 217
If dimensions contains hour, use data_state=hourly_all and a start_date within the most recent 10 days.
- Very specific: line 302
Start diagnosis with gsc-mcp doctor.
- Very specific: line 330
Never print credential contents.
- Very specific: line 332
Never test writes on a real client property.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — gsc-mcp
For an AI agent working with this repository. This is a local Google Search Console MCP server: one Go binary over stdio, using the user's own Google account to query Search Console properties they are already allowed to access.
Choose the right path first:
| Task | Read |
| Help a user install the server | The Install section here, then INSTALL.md for the complete procedure. |
| Analyse data after it is installed | The Use section here. |
Install
The whole install is six commands, in this order
Do not improvise an order, and do not jump from the binary to OAuth. Every command below is executed by you, the agent, through your terminal tool. The user's only task is choosing a Google account and ticking both consent checkboxes in the browser page that gcloud opens.
1. Install the binary.
curl -fsSL https://raw.githubusercontent.com/geniushub-seo/gsc-mcp/main/install.sh | bashirm https://raw.githubusercontent.com/geniushub-seo/gsc-mcp/main/install.ps1 | iexThe installer prints the absolute path it installed to and does not change
PATH. Use that absolute path in every later command; do not assume gsc-mcp
resolves.
2. Run these six commands in order.
gcloud auth login
gcloud projects list
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform
gcloud auth application-default set-quota-project PROJECT_ID
gcloud services enable searchconsole.googleapis.com --project=PROJECT_ID
"$HOME/.local/bin/gsc-mcp" doctorPROJECT_ID is an id from the gcloud projects list output. Substitute it
yourself; never send the literal placeholder, and never ask the user for a
project id you have not tried to read from that command first.
Each of the following has broken a real installation. None is optional:
gcloud auth loginandgcloud auth application-default loginare two separate logins. The first makesgcloud projects listwork; the second creates the credentials this server reads. Doing only the second leavesgcloud projects listfailing with an expired-credentials error.- The ADC consent page has two checkboxes. Both must be ticked, or the
login fails with
cloud-platform scope is required but not consented. - A fresh GCP project does not have the Search Console API enabled, so the
gcloud services enablestep is required. Skipping it produces a 403 that names a quota project and reads like a permission problem. - An empty
gcloud projects listmeans the user has no GCP project. Send them to https://console.cloud.google.com/projectcreate, then repeat from step 2. set-quota-projectexiting 1 withdoes not have the "serviceusage.services.use" permission on this projectmeans the Google account you signed in with has no rights on that project. Retrying the same command never clears it. Either sign in again (both logins) with an account that does have rights, or ask the project's administrator to grant the current accountroles/serviceusage.serviceUsageConsumer. Once granted, re-rungcloud auth application-default login: it attaches the quota project by itself, so theset-quota-projectstep may already be satisfied.- On Windows, gcloud installed with
winget install Google.CloudSDKis not on the PATH of the current shell. It lives at%LOCALAPPDATA%\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd; use that absolute path or open a new shell. - An account that sees no property at https://search.google.com/search-console is not an MCP installation problem. Confirm the account before debugging.
3. When doctor prints list_sites OK, wire the client.
Run gsc-mcp setup, finish the selected client's configuration, restart that
client or open a new session, and verify its MCP server list contains gsc.
Only then call list_sites. See INSTALL.md for the full
client-specific procedure.
If any command fails, run gsc-mcp doctor again and read its output before
changing anything: it runs every check plus one real list_sites call, writes
no files, and prints the fix for what it finds.
Browser consent checkpoint: agent owns the terminal
The agent must execute every shell / PowerShell command. Never tell a novice
user to open Terminal, copy a command, or paste terminal output back into chat.
Before starting OAuth, tell the user that a Google sign-in page will open and
that their only task is to choose an account and approve access. Then run this
command yourself through the terminal tool with enough time for browser
consent: step 2's gcloud auth application-default login.
Keep that command running while the user completes Google's browser UI. The
human owns the consent click; the agent owns command entry, process management,
and every follow-up command. When it exits successfully, confirm the credential
file exists with ls, never cat, then continue with the remaining commands
in step 2.
On Windows, use the absolute path printed by install.ps1. On POSIX, the
absolute "$HOME/.local/bin/gsc-mcp" avoids a false command not found when
~/.local/bin is not yet on PATH.
For Codex, do not use the repository .mcp.json; Codex MCP configuration lives
in ~/.codex/config.toml or a trusted project's .codex/config.toml. The safe
CLI path is:
codex mcp list
# Only when the first list does not contain gsc:
codex mcp add gsc -- "$HOME/.local/bin/gsc-mcp"
codex mcp listThe current Codex session will not gain the new tool. Restart Codex or start a
new session after gsc appears in the list.
Six common mistakes
- Sending the user to Terminal for OAuth. The agent starts the login command; the user interacts only with the Google page that opens.
- Skipping
set-quota-project. ADC belongs to a personal account, not a GCP project; without this command every query returns 403. - Downloading a Windows executable manually. Use
install.ps1: a manual download skips SHA-256 verification and SmartScreen unblocking and often lands outside PATH. - Printing credential contents. Use
lsonly to confirm a file exists; never usecator paste credentials into chat. - Stopping after printing an OAuth command. Keep the terminal process alive, wait for browser consent, then continue automatically from quota-project setup.
- Assuming a running client hot-loads MCP configuration. Verify the server
list, then restart or open a new session before calling
list_sites.
Use gsc-mcp doctor, not hand-written JSON-RPC, for verification
gsc-mcp doctorIt checks the full environment and performs one real list_sites call without
writing files. On failure, it prints the corrective command.
gsc-mcp setup --dry-run is not a credential check: it skips API calls.
Use
Nine tools
| Tool | Purpose | Key constraint |
list_sites | List accessible properties | No arguments. Call it first if the property format is unclear. |
get_site | Get a property's permission level | — |
query_search_analytics | Core clicks / impressions / CTR / position query | row_limit defaults to 150, maximum 25,000. |
compare_periods | Compare two periods and calculate deltas | Periods must have equal length; otherwise invalid_input. Default row_limit is 100. |
inspect_url | Inspect Google's indexed state for URLs | 1–10 URLs per call, issued serially. |
manage_sitemaps | List / get / submit / delete sitemaps | submit and delete are disabled by default. |
find_ctr_gaps | Query+page pairs that rank well but are clicked less than their position peers — the shortlist for title rewrites | Position window defaults to 1–20, min_impressions to 100, row_limit to 50 (max 1,000). |
find_page_two_queries | Queries ranking just off page one with real impression volume — the shortlist for adding content or internal links | Position window defaults to 11–20, min_impressions to 50, row_limit to 50 (max 1,000). |
find_declining_pages | Pages that lost clicks between two equal-length periods, each classified as position_drop, impressions_drop, ctr_drop or unclear | Periods must have equal length. min_click_drop defaults to 10, row_limit to 50 (max 1,000). |
Flexible site_url input
The server normalizes input; do not ask the user to pre-format it.
| Input | Sent as |
example.com | sc-domain:example.com |
https://example.com | sc-domain:example.com |
https://example.com/ | https://example.com/ — trailing slash explicitly means URL-prefix. |
https://example.com/blog | https://example.com/blog/ |
The server queries only that one normalized property and never switches to
another. If it receives 403 it returns permission_denied, and the error lists
every accessible property with its permission level; show that list to the user
and let them choose rather than guessing.
Four output traps
- Always read
truncatedandscan_capped.truncated=truemeans the result is the first N rows of a larger set.scan_capped=truemeans even the scan was incomplete, so top-N results can be missing candidates. - The API returns top rows only. Their sum does not equal the Search Console UI total.
- Average position is a weighted average of impressions, not a literal rank.
- Every
compare_periodsdelta is B minus A.ctr_aandctr_bare 0–1 fractions;ctr_delta_ppis percentage points. Negativeposition_changemeans improvement. Keys that occur in only one period useonly_inand omitposition_change; never treat an omitted field as zero.
Parameters that silently give the wrong answer
- To exclude brand terms, use
excludingRegexindimension_filter_groups. It uses RE2 and rejects lookarounds and backreferences. To rank by impressions, CTR, or position, set
sort_by. GSC itself only orders by clicks. The server scans up to 25,000 rows and sorts locally whensort_byis set.Tool sort_byvaluesDefault direction query_search_analyticsclicks(default),impressions,ctr,positionFirst three descending; positionascending.compare_periodsclicks_delta(default),impressions_delta,ctr_delta_pp,position_changeDeltas descending; position_changeascending.For the biggest ranking improvements, call
compare_periodswithsort_by=position_change.- If
dimensionscontainshour, usedata_state=hourly_alland astart_datewithin the most recent 10 days. data_statedefaults toall, matching the GSC UI including provisional data. Usefinalonly when the analysis requires finalized data.- Dates are in Pacific Time. Data is delayed 2–4 days and retained for about 16 months; an empty result from the newest days usually means data is not yet available.
Writes are disabled by default
| Action | Requirement |
list / get | Always available |
submit | GSC_ENABLE_WRITE=true |
delete | GSC_ENABLE_WRITE=true and GSC_ALLOW_DESTRUCTIVE=true |
The tool remains visible in tools/list when flags are absent, but write calls
return write_disabled without calling the API.
ADC note: GSC_ENABLE_WRITE=true is still required as the local write
gate, even after re-login with write scope. The flag cannot add scopes to an
existing ADC token, so writes also need a token issued with webmasters, not
webmasters.readonly.
Included skills
Six skills live under .agents/skills/:
| Skill | Typical request |
nonbrand-performance | “Who finds me without searching for my company name?” |
monthly-report | “How did the site perform this month?” |
index-health | “Has Google seen my new pages?” |
ctr-gaps | “Which pages rank but get no clicks? Which titles should I rewrite?” |
traffic-decline-diagnosis | “Why did traffic drop?” |
gsc-recipes | Any other question: routes the question to an exact tool call. |
The three computed tools return arithmetic, not advice. ctr-gaps and
traffic-decline-diagnosis carry the reading rules that keep the arithmetic
from producing bad recommendations — read the skill before acting on those
tools' output.
Since v0.6.0 install.sh and install.ps1 unpack these skills into
~/.claude/skills/ alongside the binary. A skill directory that is already
there is never overwritten — the installer prints keep and moves on. That
protects local edits, and it also means re-running the installer does not
upgrade a skill the user already has. If a user reports skill behaviour that
does not match this document, check whether ~/.claude/skills/<name>/ holds an
older copy; moving it aside and re-running the installer is the fix.
Native agent configuration
This repository places each agent's configuration in the location that agent recognizes. Do not duplicate these instructions or add credentials to the repo.
| Agent | Automatically read content |
| Claude Code | .mcp.json, .claude-plugin/, and the plugin's .agents/skills/ |
| Codex | This root AGENTS.md and .agents/skills/; MCP itself must be added through Codex config.toml or codex mcp add |
| Cursor | .cursor/mcp.json and .cursor/rules/gsc-mcp.mdc |
For any agent, the first real query should be list_sites when the property is
not unambiguous. Never guess a property or read or print credentials.
Troubleshooting
Diagnose the symptom first instead of inferring a cause.
| Symptom | Actual cause | Do not | Fix |
403 containing requires a quota project | ADC has no quota project, and the project it names may not have the API on | Ask the user to add a GSC user | gcloud auth application-default set-quota-project PROJECT_ID, then gcloud services enable searchconsole.googleapis.com --project=PROJECT_ID |
auth_failed containing cannot fetch token or invalid_grant | Refresh token expired | Reinstall the binary | Re-run application-default login |
gcloud projects list says credentials expired immediately after ADC login | It uses a separate token | Re-run application-default login | Run gcloud auth login |
Windows says gcloud is not recognized | Installed but absent from PATH | Re-run winget install | Use %LOCALAPPDATA%\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd |
submit / delete rejected | Local write gate closed, or ADC token is still readonly | Skip GSC_ENABLE_WRITE=true after re-login | Set GSC_ENABLE_WRITE=true and re-login with webmasters if using ADC |
| A query is empty despite known traffic | Date range is in the 2–4 day lag or outside retention | Diagnose permissions | Move end_date back several days |
gcloud auth login and gcloud auth application-default login store separate
credentials. The first serves the gcloud CLI; the second serves gsc-mcp.
The fixed error codes are invalid_input, auth_failed, permission_denied,
not_found, quota_exceeded, upstream_error, and write_disabled.
Start diagnosis with gsc-mcp doctor. To see which credential source was
selected (for example, a forgotten GOOGLE_APPLICATION_CREDENTIALS overriding
ADC), use:
GSC_LOG_LEVEL=debug gsc-mcpDeliberate exclusions
State that the server does not support these requests; do not approximate them with another tool:
- Requesting indexing: Google's Indexing API is limited to JobPosting and BroadcastEvent.
- Adding or deleting properties: adding still requires UI verification and deletion is too risky.
- Coverage, Core Web Vitals, and link reports: the official API has no such endpoints.
- Listing all indexed URLs:
inspect_urlcan inspect only known URLs, up to 10 at a time. - Testing the live version of a page:
inspect_urlreports Google's indexed version, which can lag the live page.
Hard boundaries
- Never print credential contents. Use
ls, notcat, to verify a file. - Errors can include client domains and brand terms; review them before sharing.
- Never test writes on a real client property.
submitanddeletehave real effects. - stdout must contain MCP JSON-RPC only. All logs go to stderr.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

