Reference
How the QueryScope MCP works.
The install line, what your agent does on the first run, every tool it can call, and the limits worth knowing before you act on a number. Written for the person reading it and for the agent you point at it.
Install
QueryScope is a hosted MCP server. There is nothing to run locally, no API key to paste, and no Google credentials that ever touch your machine. Add the URL, then authorize once in the browser.
claude mcp add --transport http queryscope https://mcp.queryscope.dev/mcp
Cursor, Cline, and Windsurf take the same URL in their MCP settings as a streamable HTTP server.
On the first call your IDE opens a browser window to authorize; you approve read-only access and
pick which site this connection defaults to. The grant is
webmasters.readonly, and you can revoke it
from your Google account at any time.
Before the MCP is useful, the site has to exist in QueryScope: add the domain and connect Search Console in the dashboard. The first data pull runs inline at that moment, so numbers are there in seconds rather than the next day.
What happens on your first run
Nothing, until you ask. An MCP server does not greet you, open a wizard, or ask a setup question: it sits in your agent's tool list and waits to be called. If you connected it and saw no reaction, that is the design working, not a failure.
-
1
Your agent gets briefed, silently.
On connect, the server hands your IDE's model a set of standing instructions: which tool to start with, the six moves it is allowed to recommend, and the rule that it must never ask you to export a Search Console ZIP. You never see this. It is written for the model.
-
2
You ask something ordinary.
"How is my site doing", "audit my search console", "what should I fix". Anything in that shape routes to
gsc_overview, which is the entry point for everything else. -
3
You get a ranked call, not a dashboard.
The overview opens with the site pulse, then the searches people arrive on, then a Fix this first list ordered by how many clicks are recoverable, and leads with a single Do next line: one page, one change, and the exact call to record it when you ship.
-
4
It asks you for the one thing it cannot work out.
Which of your pages actually sell. See below: this is the only setup step, and skipping it is the difference between a useful queue and a confident wrong answer.
The one setup step
Tell it which pages sell
QueryScope measures clicks and stops there. It cannot see a signup, a trial, or a sale, which means it has no way of knowing that your pricing page is worth more than a blog post pulling five times the traffic. Left alone, it will rank by recoverable clicks and lead you straight at the blog post.
Your agent has your repo open, so it can answer this far better than any question we could ask on a signup form. Tell it to record the answer once:
> look at this repo and tell QueryScope which pages we sell from
The agent finds the pricing, checkout, signup and product routes and calls
gsc_set_focus. It persists, so later
sessions build on it instead of re-deriving it, and each call replaces the previous one when
something changes. After that the overview leads with a real fix on a page that matters to the
business, and says that is why it chose it.
Nothing else moves. The queue stays ordered by recoverable clicks, because that is a measured number and "this page sells" is not a quantity we can put on the same scale. Your declaration changes which fix leads, never the estimates underneath it.
The loop
Every tool is one of four verbs. If a thing is not one of these, QueryScope does not do it.
Read
Pull your own Search Console: clicks, impressions, position, queries, countries, indexing.
Decide
Rank what is worth doing by the clicks each change could recover, and name one to do next.
Do
Your agent makes the edit in your repo. QueryScope never writes to your site.
Measure
Record the change, then compare the page before and after so you know whether it worked.
The six moves
Every fix QueryScope surfaces is one of these, and only these. The list is closed on purpose: for a site that already has traffic, growth is a short set of levers, and all six are visible in Search Console data. There is no seventh, because QueryScope stops at the click.
Get the page indexed
The gate. Nothing you do to a page can pay off while the page sits outside the index, so this is checked before anything else.
Win the click you already earn
A page ranking roughly 3 to 10 whose click rate sits below the curve for its position. Usually a title and meta rewrite. Sometimes an AI answer is taking the click instead, and QueryScope says so rather than sending you to rewrite a title that was never the problem.
Push a near miss onto page 1
A query sitting around position 8 to 20, close enough that content and internal links can move it. A title tweak cannot.
Revive a decaying page
A page quietly losing clicks against its own recent history. QueryScope separates a real decline from a site-wide Google update, because those need opposite responses.
Fix the fit
A page ranking for the wrong kind of search. The right traffic, not just more of it.
Link to an under-linked page
A page with real demand stuck below page 1. QueryScope cannot see your link graph, so it names candidates and your agent checks the repo before adding anything.
The tools
Twelve, in two groups. You rarely name one yourself: ask a question in plain language and your agent picks. They are listed so you can tell whether an answer came from your data or from the model's imagination.
Read your data
| Tool | Answers |
|---|---|
gsc_overview |
How is the whole site doing, and what should I fix first? The entry point: pulse, history, indexing, movers, and the ranked fix list. |
gsc_pages |
Which pages are up, down, under-clicked, decaying, or stuck just off page 1. |
gsc_queries |
What searches the site ranks for, what they intend, and which carry low buying value. |
gsc_page_queries |
What one specific page ranks for. Use it to check whether a page pulls the traffic its role implies. |
gsc_countries |
Where the traffic comes from. Whether those markets fit what you sell is your call, not a grade in the data. |
gsc_indexing |
What Google has indexed, what it declined, and why, grouped by whether you can act on it. |
gsc_sites |
Which sites this connection can read. Useful when one account covers several. |
Record and measure
| Tool | Does |
|---|---|
gsc_set_focus |
Records which pages you sell from, so the queue can lead with value instead of volume. |
gsc_mark_fixed |
Marks a change at the moment you ship it, with what you changed and what you expect. This starts the before and after. |
gsc_lift |
Compares the page before and after, once enough time has passed to mean anything, and shows your track record per kind of fix. |
gsc_review |
Freezes your judgment of a measured result so the next session builds on it. |
gsc_resolve |
Records a decision not to fix something, and why. That flag stops resurfacing until it gets materially worse. |
The recording tools are the half people skip, and skipping them is what makes SEO feel unfalsifiable. A change whose result lands six weeks later is forgotten by then unless something wrote it down at the time.
What it cannot see
QueryScope reads one machine: search traffic. Knowing where it ends is what keeps the recommendations honest, so here is the boundary in full.
Anything past the click
Signups, revenue, what someone did on the page. Search Console stops at the click and so do we. No fix here should ever be sold to you as lifting conversions.
Backlinks
Search Console carries no link data at all. Off-site authority shows up only as a ceiling: when a recorded fix settles and still reads flat, that is usually the cause.
The competitive search results
What ranks above you is a separate read, available on the plans that include it, and used narrowly to explain a click that a rewrite would not recover.
Demand you do not already have
Search Console reports the searches you already appear for. It cannot tell you about a market you have never ranked in.
Whether a page is meant to convert
That lives in your repo, not in your search data. It is why the tools keep asking your agent to go and read the page.
One data caveat worth internalizing. Page-level numbers are near complete and are the source of truth for volume. Query-level numbers always under-count, because Google anonymizes rare searches. Read queries for what they say about intent and alignment, never as a total.
Troubleshooting
It answered about the wrong site.
A connection has one default site, and it may not be the repo you have open. Tell your agent to pass the domain explicitly, or ask it to run gsc_sites and pick. Every read names which site it read at the top, so check that line first.
A new tool does not show up.
IDEs cache the tool list when they connect. After an update that adds a tool, reconnect the MCP server. Changes to what existing tools return need no reconnect and appear immediately.
No data yet.
Connect Search Console for the site in the dashboard. If it is connected and still empty, the property may have been added to Google recently: Search Console itself has no history to give us until it has collected some.
The numbers do not match the Search Console interface.
Almost always the window. The overview compares the last 30 days against the prior 30; the web interface often defaults to three months. Compare the same range before assuming a gap. Data also settles for two to three days after the fact.
The agent wants me to export a ZIP.
It has an older Search Console skill installed that is overriding the live tools. Adding the QueryScope rules to your repo fixes it, since a repo rule outranks a tool description.
Read your own Search Console where you write the fix.
One line to install, your real data, and a ranked call on what to change next.
From $14.99/mo · Claude Code, Cursor, Cline & Windsurf