MCP toolsSearch and assistantsUpdated
Searches
What does mttr_queries do?
The searches a site’s pages were shown for, from Search Console, with clicks, impressions and average place: by query, by page, or only those close to the top. A key may make this call on the sites it has claimed.
When to use it
- You want to know what people search to find a site.
- You want searches sitting just off the first page.
What you ask
You say“Which searches is example.com close to the top for?”
Your assistant calls
mttr_queries({ site: "example.com" })
| Argument | Type | Needed | What it is |
|---|---|---|---|
site | Text | Yes | The site, as a domain such as example.com. |
show | One of these | No | queries (the default), pages, near: queries close to the top, unanswered: searches no passage on the site comes close to, brand searches left out, or better: searches another page reads closer to than the one Google shows. The last two are most seen first.queriespagesnearunansweredbetter |
page | Text | No | A full page address, to list only the queries that page was shown for. |
limit | Number | No | How many to return. |
offset | Number | No | How many to skip, for the next part of a long list. |
What comes back
- Each search with clicks, impressions and average place.
- With show set to unanswered, the searches no page on the site answers; with better, those where another of its pages reads closer than the one Google shows.
- Searches read from Search Console are marked as quoted. A site whose Search Console has not been read gets nothing, and the answer says so.
| Search | Clicks | Shown | Place |
|---|---|---|---|
| drain cleaning near me | 38 | 1,204 | 6.2 |
| septic pumping cost | 12 | 880 | 9.8 |
| clogged sink fix | 4 | 610 | 14.1 |
Made-up sites and figures, to show the shape of the answer. The answer itself is JSON.
Over HTTP
It is GET /api/v1/sites/{site}/queries, with your key as a bearer token:
curl "https://mttr.si/api/v1/sites/example.com/queries" \
-H "Authorization: Bearer $MTTR_KEY"When it fails
| When | Status | What to do |
|---|---|---|
| Your assistant has no key yet | 401 over MCP | Sign up with mttr_signup, then connect again with the key it gives. |
| The key has not claimed the site | 404 | Claim it with mttr_claim, then mttr_claim_check. |
Every error’s wording is in the API reference.
The call in full, with its HTTP address, each argument’s type, who may make it and the call in four languages, is mttr_queries in the API reference.