MCP tool reference

This reference is for users configuring an MCP client or inspecting which Searcherries data their assistant retrieves. The server is read-only: it lists your projects and reads the data Searcherries has already stored. It never changes a project and never calls Google, Bing or an AI platform on your behalf.

Connect to https://app.searcherries.com/mcp/searcherries using authorized OAuth or a personal access token. See connection options.

Recommended call order

For a practical request such as "what should I work on next", start with get-action-plan. For a detailed investigation:

list-projects to find the project id.
get-project-summary for one compact snapshot of that project (about 16 KB).
A focused tool for the rows you need: get-ai-answers, get-search-performance, get-competitors, get-citations, get-ai-traffic.
get-project-data when you want several datasets in one call or a legacy section.

The prompts action-plan, geo-audit, content-gaps, competitor-gap, page-brief, question-review and weekly-report contain these sequences as ready recipes. In Claude and Claude Code they appear in the prompt (slash command) menu once the server is connected.

Periods

AI visibility data (metrics, answers, competitors, citations) uses report periods anchored to the latest completed check: last_30_days (default), last_60_days, last_90_days, this_year, last_year. A period without enough history falls back to the nearest available one; the response says which period was used.

Connected sources (Google Search Console, Bing Webmaster Tools, GA4) are stored as rolling windows ending on the collection day: 30d, 90d, 365d. Each response carries period_start, period_end, fetched_at and is_stale.

get-action-plan

Prioritized next steps for one project. It accepts a project name or domain, so it needs no earlier list-projects call.

Argument	Required	Meaning
`project`	No	Brand name, domain, website URL or project id as text. Omit it when the account has one project. Do not combine it with `project_id`.
`project_id`	No	A known project id instead of `project`.
`audience`	No	`business` (default) for traffic and business priorities, `marketing` for brand answers and content, `seo` for search pages and queries.
`period`	No	AI visibility period. Default `last_30_days`. Search and traffic use their own rolling 30-day snapshots.
`limit`	No	Maximum number of actions, 1 to 10 (default 5). Fewer are returned when the evidence is thin.

The response has a status (ready, needs_data, no_priority_signals, or needs_project when the project is missing or ambiguous), the actions, data_notes about missing or stale sources, and a compact snapshot of the project. Each action carries a title, a suggested owner, the next step, dated evidence, a success measure, a link to the matching Searcherries report and a next_call with the tool and arguments that return the supporting rows.

Actions come from four stored signals: answers that are negative about the brand or name a drawback, answers where the brand is not named, Search Console and Bing queries with many impressions and few clicks, and the landing pages of AI visitors. The order follows the chosen audience. It is a suggestion and does not estimate impact, effort or revenue. When several projects match the name, the tool returns the candidates and the assistant has to ask which one you mean.

list-projects

Lists the projects of the authenticated account with status, tracked AI platforms, connected sources and their freshness, counts of stored data and the latest check date. It takes no arguments.

get-project-summary

One compact snapshot of a project. Blocks: profile (brand, market, business profile), questions (primary and additional customer questions with their last and next check), ai_visibility (score, mentions by platform, change against the previous period, share of voice), answer_insights (how often and how prominently the brand is named, negative and off-topic answers), competitors (own brand and top 10), citations (top cited domains), search (30-day Google and Bing totals with top 5 lists), ai_traffic (30-day GA4 AI traffic with engaged sessions, key events, conversions and the share of all site sessions), connections (health) and recommendations (latest summary).

Argument	Required	Meaning
`project_id`	Yes	Project id from `list-projects`.
`period`	No	AI visibility period. Default `last_30_days`.
`include`	No	Blocks to include; omit for all.

get-ai-answers

Stored AI answers, one row per check and platform, joined with their answer insights: prominence_level (0 not named, 1 named in passing, 2 one of the options, 3 top recommendation), on_topic, names_brands, brand_sentiment, brand_drawback, evidence_quote, cited URLs and the web searches the platform ran. brand_mentioned is null for answers the nightly insight backfill has not judged yet.

Argument	Required	Meaning
`project_id`	Yes	Project id.
`period`	No	Report period; ignored when `since`/`until` are given.
`since`, `until`	No	Check dates, `YYYY-MM-DD`.
`prompt_id`	No	One customer question.
`platform`	No	One AI platform.
`prominence_max`	No	Keep answers with prominence at most this level. `1` lists the gaps.
`only_flagged`	No	Only negative, drawback or off-topic answers.
`include_answer_text`	No	Include the answer text. Caps the page at 20 rows.
`max_answer_chars`	No	Characters per answer when text is included (200 to 20000, default 1200).
`limit`, `offset`	No	Pagination, 1 to 100 rows.

get-search-performance

Google Search Console or Bing Webmaster Tools data for one window.

Argument	Required	Meaning
`project_id`	Yes	Project id.
`source`	No	`google` (default) or `bing`.
`period`	No	`30d` (default), `90d`, `365d`.
`dataset`	No	`summary` (default), `top_queries`, `top_pages`, `top_countries`, `queries_by_country`, `opportunities`, `trends`, `ai_question_queries` (Google only), `daily`, `history`.
`query_contains`, `page_contains`, `country`	No	Text filters on the list datasets.
`min_impressions`, `min_clicks`, `min_position`, `max_position`	No	Numeric filters.
`sort`	No	`clicks` (default), `impressions`, `ctr`, `position`.
`limit`, `offset`	No	Pagination for list datasets.

Lists are the stored top sample (up to 50 rows per dimension, up to 1000 question-shaped queries), not an exhaustive export. history sums the daily series per calendar month.

get-competitors

Argument	Required	Meaning
`project_id`	Yes	Project id.
`period`	No	Report period.
`dataset`	No	`ranking` (default), `detail`, `history`.
`competitor`	For `detail`	Brand name or a fragment of it.
`include_highlights`, `highlights_per_platform`	No	Highlight sentences per platform in the ranking (default 3, max 5).
`limit`, `offset`	No	Rows for `ranking` (max 50) or months for `history`.

ranking returns one row per brand for the period, the own brand included, ranked by visibility. history returns the stored month-by-month snapshots.

get-citations

Argument	Required	Meaning
`project_id`	Yes	Project id.
`period`	No	Report period.
`group_by`	No	`url` (default) or `domain`.
`platform`, `prompt_id`, `url_contains`	No	Filters for the URL grouping.
`own_site_only`	No	Only URLs on the project website.
`limit`, `offset`	No	Pagination.

get-ai-traffic

Argument	Required	Meaning
`project_id`	Yes	Project id.
`period`	No	`30d` (default), `90d`, `365d`.
`dataset`	No	`summary` (default), `sources`, `landing_pages`, `daily`, `history`.
`source`	No	One AI source (`chatgpt`, `gemini`, `perplexity`, `claude`, `copilot`, `meta_ai`, `other_ai_assistants`, `ai_overviews`).
`path_contains`	No	Filter on landing page paths.
`limit`, `offset`	No	Pagination for `landing_pages`.

get-project-data

Several datasets in one call. Omitting sections returns a compact overview profile with every dataset except ai_visibility.summary, which repeats the others: 10 rows per list, the 30-day snapshot of each connected source, no answer text.

Argument	Required	Meaning
`project_id`	Yes	Project id.
`sections`	No	Dataset identifiers (below).
`period`	No	Report period for the AI visibility sections.
`limit`, `offset`	No	Rows per paginated section, 1 to 100 (default 25).
`include_answer_text`	No	Answer text in `ai_visibility.mentions` (max 20 rows).

Dataset identifiers

Identifier	Contents
`ai_visibility.summary`	The same snapshot as `get-project-summary`. Only returned when requested by name.
`ai_visibility.metrics`	Live visibility KPIs for the period: score, mentions by platform, citations, average position, change against the previous period, share of voice.
`ai_visibility.answer_insights`	Summary of the answer insights for the period.
`ai_visibility.search_queries`	Web searches the AI platforms ran per customer question.
`ai_visibility.topics`	Topics with their question counts.
`ai_visibility.prompts`	Customer questions and their tracking cadence (inactive onboarding suggestions are hidden).
`ai_visibility.mentions`	Stored answers with insights, as in `get-ai-answers`.
`citations.top_sites`	Most-cited domains for the period.
`citations.urls`	Cited URLs grouped per URL for the period.
`competitors`	Competitors aggregated for the period, own brand included.
`recommendations`	Stored recommendation articles (markdown).
`trust_mentions`	Historical review-platform mentions. No longer collected.
`ga4.ai_traffic`	GA4 snapshots, newest per window.
`google_search_console.performance`	Search Console snapshots, newest per window, without the daily series.
`bing_webmaster_tools.performance`	Bing snapshots, newest per window, without the daily series.
`project.business_profile`	The business profile and onboarding context of the project.
`history`	Monthly history: visibility from competitor snapshots, Google and Bing clicks and impressions, GA4 AI sessions.
`connections`	Connection health of GA4, Search Console and Bing.

Pagination

Paginated datasets return offset, limit, returned, total and has_more. When has_more is true, request the next page with a larger offset. Requesting one dataset at a time keeps pagination simple.

Size and freshness

Responses are single JSON documents. The project summary stays around 16 KB and the action plan within about 24 KB; focused tools and single sections stay within about 40 KB at default limits. Check period, fetched_at and is_stale before combining numbers from different datasets.

An authentication error calls for reconnection. A project-not-found error means a wrong id or a project outside the authorized account. Unknown datasets, sections and out-of-range values are rejected. These tools do not refresh external services or alter projects. Read about data updates.