agentleFS
geniushub-seogeniushub-seo/gsc-mcp/AGENTS.md

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.

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
  1. Distinctive:

    Do not improvise an order, and do not jump from the binary to OAuth.

    line 20
  2. Very specific:

    Run gsc-mcp setup, finish the selected client's configuration, restart that client or open a new session, and verify its MCP server list …

    line 84
  3. Very specific:

    Only then call list_sites.

    line 86
  4. Very specific:

    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 …

    line 89
  5. Distinctive:

    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 …

    line 97
  6. Distinctive:

    Keep that command running while the user completes Google's browser UI.

    line 102
  7. Very specific:

    Downloading a Windows executable manually: Use install.ps1: a manual download skips SHA-256 verification and SmartScreen unblocking and …

    line 132
  8. Very specific:

    Printing credential contents: Use ls only to confirm a file exists.

    line 135
  9. Distinctive:

    Stopping after printing an OAuth command: Keep the terminal process alive, wait for browser consent, then continue automatically from …

    line 137
  10. Very specific:

    Assuming a running client hot-loads MCP configuration: Verify the server list, then restart or open a new session before calling list_sites.

    line 140
  11. Very specific:

    Always read truncated and scan_capped.

    line 190
  12. Very specific:

    Every compare_periods delta is B minus A.

    line 196
  13. Very specific:

    If dimensions contains hour, use data_state=hourly_all and a start_date within the most recent 10 days.

    line 217
  14. Very specific:

    Start diagnosis with gsc-mcp doctor.

    line 302
  15. Very specific:

    Never print credential contents.

    line 330
  16. Very specific:

    Never test writes on a real client property.

    line 332

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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:

TaskRead
Help a user install the serverThe Install section here, then INSTALL.md for the complete procedure.
Analyse data after it is installedThe 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 | bash
irm https://raw.githubusercontent.com/geniushub-seo/gsc-mcp/main/install.ps1 | iex

The 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" doctor

PROJECT_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 login and gcloud auth application-default login are two separate logins. The first makes gcloud projects list work; the second creates the credentials this server reads. Doing only the second leaves gcloud projects list failing 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 enable step is required. Skipping it produces a 403 that names a quota project and reads like a permission problem.
  • An empty gcloud projects list means the user has no GCP project. Send them to https://console.cloud.google.com/projectcreate, then repeat from step 2.
  • set-quota-project exiting 1 with does not have the "serviceusage.services.use" permission on this project means 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 account roles/serviceusage.serviceUsageConsumer. Once granted, re-run gcloud auth application-default login: it attaches the quota project by itself, so the set-quota-project step may already be satisfied.
  • On Windows, gcloud installed with winget install Google.CloudSDK is 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 list

The 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

  1. Sending the user to Terminal for OAuth. The agent starts the login command; the user interacts only with the Google page that opens.
  2. Skipping set-quota-project. ADC belongs to a personal account, not a GCP project; without this command every query returns 403.
  3. Downloading a Windows executable manually. Use install.ps1: a manual download skips SHA-256 verification and SmartScreen unblocking and often lands outside PATH.
  4. Printing credential contents. Use ls only to confirm a file exists; never use cat or paste credentials into chat.
  5. Stopping after printing an OAuth command. Keep the terminal process alive, wait for browser consent, then continue automatically from quota-project setup.
  6. 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 doctor

It 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

ToolPurposeKey constraint
list_sitesList accessible propertiesNo arguments. Call it first if the property format is unclear.
get_siteGet a property's permission level—
query_search_analyticsCore clicks / impressions / CTR / position queryrow_limit defaults to 150, maximum 25,000.
compare_periodsCompare two periods and calculate deltasPeriods must have equal length; otherwise invalid_input. Default row_limit is 100.
inspect_urlInspect Google's indexed state for URLs1–10 URLs per call, issued serially.
manage_sitemapsList / get / submit / delete sitemapssubmit and delete are disabled by default.
find_ctr_gapsQuery+page pairs that rank well but are clicked less than their position peers — the shortlist for title rewritesPosition window defaults to 1–20, min_impressions to 100, row_limit to 50 (max 1,000).
find_page_two_queriesQueries ranking just off page one with real impression volume — the shortlist for adding content or internal linksPosition window defaults to 11–20, min_impressions to 50, row_limit to 50 (max 1,000).
find_declining_pagesPages that lost clicks between two equal-length periods, each classified as position_drop, impressions_drop, ctr_drop or unclearPeriods 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.

InputSent as
example.comsc-domain:example.com
https://example.comsc-domain:example.com
https://example.com/https://example.com/ — trailing slash explicitly means URL-prefix.
https://example.com/bloghttps://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 truncated and scan_capped. truncated=true means the result is the first N rows of a larger set. scan_capped=true means 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_periods delta is B minus A. ctr_a and ctr_b are 0–1 fractions; ctr_delta_pp is percentage points. Negative position_change means improvement. Keys that occur in only one period use only_in and omit position_change; never treat an omitted field as zero.

Parameters that silently give the wrong answer

  • To exclude brand terms, use excludingRegex in dimension_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 when sort_by is set.

    Toolsort_by valuesDefault direction
    query_search_analyticsclicks (default), impressions, ctr, positionFirst three descending; position ascending.
    compare_periodsclicks_delta (default), impressions_delta, ctr_delta_pp, position_changeDeltas descending; position_change ascending.

    For the biggest ranking improvements, call compare_periods with sort_by=position_change.

  • If dimensions contains hour, use data_state=hourly_all and a start_date within the most recent 10 days.
  • data_state defaults to all, matching the GSC UI including provisional data. Use final only 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

ActionRequirement
list / getAlways available
submitGSC_ENABLE_WRITE=true
deleteGSC_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/:

SkillTypical 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-recipesAny 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.

AgentAutomatically read content
Claude Code.mcp.json, .claude-plugin/, and the plugin's .agents/skills/
CodexThis 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.

SymptomActual causeDo notFix
403 containing requires a quota projectADC has no quota project, and the project it names may not have the API onAsk the user to add a GSC usergcloud 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_grantRefresh token expiredReinstall the binaryRe-run application-default login
gcloud projects list says credentials expired immediately after ADC loginIt uses a separate tokenRe-run application-default loginRun gcloud auth login
Windows says gcloud is not recognizedInstalled but absent from PATHRe-run winget installUse %LOCALAPPDATA%\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd
submit / delete rejectedLocal write gate closed, or ADC token is still readonlySkip GSC_ENABLE_WRITE=true after re-loginSet GSC_ENABLE_WRITE=true and re-login with webmasters if using ADC
A query is empty despite known trafficDate range is in the 2–4 day lag or outside retentionDiagnose permissionsMove 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-mcp

Deliberate 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_url can inspect only known URLs, up to 10 at a time.
  • Testing the live version of a page: inspect_url reports Google's indexed version, which can lag the live page.

Hard boundaries

  • Never print credential contents. Use ls, not cat, to verify a file.
  • Errors can include client domains and brand terms; review them before sharing.
  • Never test writes on a real client property. submit and delete have real effects.
  • stdout must contain MCP JSON-RPC only. All logs go to stderr.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.