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 First run Tools The seven moves What it cannot see Troubleshooting

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 Code

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.

Then tell your agent it is there

Optional, and the highest-value minute you will spend after installing. An MCP server is passive: your agent sees the tools sitting in a list and decides for itself whether to reach for them. A rule file in your repo is an instruction, and instructions win. Without one, an agent that also knows the old "download a Search Console export and parse it" routine will follow the routine instead.

CLAUDE.md

## Search performance: use the QueryScope MCP

The QueryScope MCP server is connected and is the source for anything about
this site's search performance: clicks, impressions, CTR, position, queries,
indexing, and which searches this site should be winning.

- Start any SEO work with `keyword` and no arguments. It researches the niche
  and names the buyer-intent searches rivals win and we do not. Do not ask
  which keywords matter: that is the question it exists to answer.
- Never download a Search Console export, ask for a ZIP, or run scripts over
  exported files. The data is live in the tools and always current.
- Record every decision in one `verdict` call: which searches to go after,
  which are not our buyer, which are real but not now. A research pass nobody
  records leaves the site with no plan.
- Once searches are declared, `work` is the loop. Call it for the next thing to
  do, make that change, then call it again with `target` and `did`.
- The plan lives at `queryscope.md`. Do not write that file yourself: `focus`
  returns its exact bytes. Leave it uncommitted for review.
- If the tools error, say so and stop. Do not fall back to exports.

Cursor reads .cursor/rules/queryscope.mdc, Cline reads .clinerules, Windsurf reads .windsurfrules. The same text works in any of them, and because it lives in your repo it takes effect the moment you save it: no reconnect.

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, that it should decide rather than hand the SEO questions back to you, that it must never ask you to export a Search Console ZIP, and that QueryScope stops at the click. You never see this. It is written for the model.
2

You ask something ordinary.

"How is my site doing", "what should we be ranking for", "what should I fix". Anything in that shape routes to keyword with no arguments, which is the entry point for everything else.
3

You get a shortlist, not a dashboard.

It names who else ranks for the searches you want, which buyer-intent searches they win and you do not, and where Search Console already has you standing on each. Your agent then judges every candidate against your repo, because it is the only reader in the loop that knows what you sell, and records the calls with verdict.
4

It brings you the one thing it cannot decide.

What the business actually is. See below: this is the only setup step, and it is the difference between being measured against the rivals who sell against you and being measured against whoever happens to rank for the same words.
5

Then the loop starts.

Once searches are declared, work hands back one at a time: the search, the page, the move, and the one fact about Google your agent cannot read out of your repo. It makes the change and says so, which is what starts the clock on measuring it.

The one setup step

Tell it what you sell

QueryScope knows a rival ranks for a search and that the phrase carries buying intent. It does not know whether you sell what that searcher wants. Without a brief it works out who your competitors are from domain overlap, which finds whoever ranks for the same words rather than whoever sells against you. On one real site that put an agency the owner had explicitly ruled out at the top of the list.

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:

> read this repo and tell QueryScope what we sell, who buys it, and who we compete with

The agent reads the landing page, pricing and product routes and calls 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 rivals it reads are the ones you actually sell against.

This is the one question to answer yourself rather than delegate. Everything after it (which searches are worth winning, which page to re-aim, what a title should say) is SEO work your agent should decide and report. What the business is is a claim about you.

The plan lives in your repo. focus renders queryscope.md and hands your agent the exact bytes to write: the searches you declared, what each is worth, and the changes proposed against them. Your agent writes the file and leaves it uncommitted. Committing it is how you agree to what it says, and a change that rewrites what a visitor reads is not recorded until you have.

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

Declare the searches worth winning, then take them in order: what you said each is worth first, then size, then how far it is from done.

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 seven 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. The menu stops there because QueryScope stops at the click: it never sees a signup or a sale, so it will never tell you a ranking fix earned you one.

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.

Rank higher on a search you already place for

The page appears and not high enough: either on page 1 with places above it, or below page 1, where Search Console goes blank and only a read of the results page can see you. Content and internal links move this. A title tweak does not.

Revive a search you have lost

Search Console used to show this site for it and shows nothing now, and the page aimed at it is absent from the results page too. It was aimed correctly and slipped, so the work is reviving that page rather than re-aiming it at something else.

Re-aim a page that is not competing

Google has the page indexed and it is nowhere in the results for the search it was aimed at, well past the first few pages. Pushing a page that is not in the race does nothing, so this re-aims it at what it can actually win.

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.

Build a page that should exist

Only once your site has a plan, because without one nothing can say a page is missing. It carries no click estimate on purpose: the traffic would land on a page that does not exist yet, so any number would be invented.

The tools

Four. 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.

Build the plan

Tool	Does
`focus`	Records what the site sells, who buys it, and which rivals it competes with, read out of your repo rather than asked of you on a form. It also renders queryscope.md and hands your agent the exact bytes to write.
`keyword`	With no arguments, researches the niche: who else ranks for the searches you want, and which buyer-intent searches they win and you do not. It also reads who is finding you now, grouped by the job behind the search and by subject, because a cluster you are visible for where nobody is shopping is not just wasted effort, it is what Google reads the site as being about. With a search named, how many people run it a month, where you stand on it, which page is aimed at it, and what to change. Your agent can also propose the searches it read out of your repo.
`verdict`	Records what was decided about each search: go after it, not our buyer, not yet, or drop one already in the plan. Fifty decisions in one call. Research nobody records leaves the site with no plan and starts from nothing next session.

Work it

Tool	Does
`work`	With no arguments, the single next thing to do: one search, one page, the move, and the one fact about Google your agent cannot read out of your repo. Your agent makes the change, then calls it again saying what it did. That is what starts the clock.

It will not hand the same target back while a change on it is still settling, and there is no flag to override that. A second edit inside the measurement window overwrites the baseline the first one is judged against, and the first change then reads as having done nothing, forever.

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

Search Console gives your position as a number and says nothing about the page around it. QueryScope reads the results page separately for the searches you declared, and labels it as what it is: one observation, in one market, on one date. Your position on page 1 always comes from Search Console; below page 1 Google records no position at all, so a read of the results page is the only thing that can speak.

How big a search is, from Search Console

Search Console only reports searches you already appear for, so at a deep rank a busy search and a dead one arrive looking identical. Demand figures are bought from a third party, shown as a band rather than a precise number, and never mixed into your position, which is always your own.

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 bound default site, and it may not be the repo you have open. Every tool takes a site parameter, and the standing instructions tell your agent to work the domain out from the repo (git remote, package.json, .env) and pass it. Every answer names the site it read, 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. Positions and impressions are read over the last 28 days; 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, so the most recent day always reads low.

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 to rank for the searches you decided to win.

Connect your site Why hosted, not self-run

$149/mo, everything included · Claude Code, Cursor, Cline & Windsurf