Referência das ferramentas MCP

Esta referência é para quem configura um cliente MCP ou quer conferir quais dados da Searcherries o assistente busca. O servidor é somente leitura: lista os seus projetos e lê os dados que a Searcherries já armazenou. Nunca altera um projeto e nunca chama o Google, o Bing ou uma plataforma de IA em seu nome.

Conecte-se a https://app.searcherries.com/mcp/searcherries com OAuth autorizado ou com um token de acesso pessoal. Veja as opções de conexão.

Ordem de chamadas recomendada

Para um pedido prático como “no que devo trabalhar agora”, comece por get-action-plan. Para uma investigação detalhada:

list-projects para encontrar o id do projeto.
get-project-summary para um panorama compacto desse projeto (cerca de 16 KB).
Uma ferramenta específica para as linhas de que você precisa: get-ai-answers, get-search-performance, get-competitors, get-citations, get-ai-traffic.
get-project-data quando quiser vários conjuntos de dados em uma só chamada ou uma seção legada.

Os prompts action-plan, geo-audit, content-gaps, competitor-gap, page-brief, question-review e weekly-report trazem essas sequências como receitas prontas. No Claude e no Claude Code, eles aparecem no menu de prompts (comandos de barra) depois que o servidor é conectado.

Períodos

Os dados de visibilidade em IA (métricas, respostas, concorrentes, citações) usam períodos de relatório ancorados na última verificação concluída: last_30_days (padrão), last_60_days, last_90_days, this_year, last_year. Um período sem histórico suficiente é trocado pelo período disponível mais próximo; a resposta informa qual período foi usado.

As fontes conectadas (Google Search Console, Bing Webmaster Tools, GA4) são armazenadas como janelas móveis que terminam no dia da coleta: 30d, 90d, 365d. Cada resposta traz period_start, period_end, fetched_at e is_stale.

get-action-plan

Os próximos passos priorizados de um projeto. A ferramenta aceita o nome ou o domínio do projeto, então dispensa uma chamada anterior a list-projects.

Argumento	Obrigatório	Significado
`project`	Não	Nome da marca, domínio, URL do site ou id do projeto como texto. Omita quando a conta tiver um só projeto. Não combine com `project_id`.
`project_id`	Não	Um id de projeto conhecido, no lugar de `project`.
`audience`	Não	`business` (padrão) para prioridades de tráfego e de negócio, `marketing` para respostas sobre a marca e conteúdo, `seo` para páginas e consultas de busca.
`period`	Não	Período de visibilidade em IA. Padrão: `last_30_days`. Busca e tráfego usam os próprios snapshots móveis de 30 dias.
`limit`	Não	Número máximo de ações, de 1 a 10 (padrão 5). Quando há poucas evidências, a resposta traz menos ações.

A resposta tem um status (ready, needs_data, no_priority_signals, ou needs_project quando o projeto está ausente ou é ambíguo), as actions, as data_notes sobre fontes ausentes ou desatualizadas e um snapshot compacto do projeto. Cada ação traz um título, um responsável sugerido, o próximo passo, evidências datadas, uma métrica de sucesso, um link para o relatório correspondente da Searcherries e um next_call com a ferramenta e os argumentos que devolvem as linhas de apoio.

As ações saem de quatro sinais armazenados: respostas negativas sobre a marca ou que apontam um ponto fraco, respostas em que a marca não é mencionada, consultas do Search Console e do Bing com muitas impressões e poucos cliques, e as páginas de destino dos visitantes que chegam pela IA. A ordem segue o público escolhido. É uma sugestão e não estima impacto, esforço nem receita. Quando vários projetos correspondem ao nome, a ferramenta devolve os candidatos e o assistente precisa perguntar a qual deles você se refere.

list-projects

Lista os projetos da conta autenticada com o status, as plataformas de IA monitoradas, as fontes conectadas e a atualidade de cada uma, as contagens de dados armazenados e a data da última verificação. Não recebe argumentos.

get-project-summary

Um panorama compacto de um projeto. Blocos: profile (marca, mercado, perfil do negócio), questions (a pergunta principal e as adicionais dos clientes, com a última e a próxima verificação), ai_visibility (pontuação, menções por plataforma, variação em relação ao período anterior, share of voice), answer_insights (com que frequência e com que destaque a marca é mencionada, respostas negativas e fora do tema), competitors (a própria marca e as 10 principais), citations (domínios mais citados), search (totais de 30 dias do Google e do Bing com listas dos 5 principais), ai_traffic (tráfego de IA de 30 dias no GA4, com sessões engajadas, eventos principais, conversões e a participação no total de sessões do site), connections (estado das conexões) e recommendations (resumo mais recente).

Argumento	Obrigatório	Significado
`project_id`	Sim	Id do projeto, obtido com `list-projects`.
`period`	Não	Período de visibilidade em IA. Padrão: `last_30_days`.
`include`	Não	Blocos a incluir; omita para receber todos.

get-ai-answers

Respostas de IA armazenadas, uma linha por verificação e plataforma, junto com as avaliações de cada resposta: prominence_level (0 não mencionada, 1 mencionada de passagem, 2 uma das opções, 3 principal recomendação), on_topic, names_brands, brand_sentiment, brand_drawback, evidence_quote, as URLs citadas e as buscas na web que a plataforma fez. brand_mentioned é null nas respostas que o processamento noturno de avaliações ainda não analisou.

Argumento	Obrigatório	Significado
`project_id`	Sim	Id do projeto.
`period`	Não	Período do relatório; ignorado quando `since`/`until` são informados.
`since`, `until`	Não	Datas de verificação, `YYYY-MM-DD`.
`prompt_id`	Não	Uma única pergunta dos clientes.
`platform`	Não	Uma única plataforma de IA.
`prominence_max`	Não	Mantém as respostas com destaque até este nível. `1` lista as lacunas.
`only_flagged`	Não	Só respostas fora do tema e respostas negativas ou com ponto fraco sustentadas por uma frase da própria resposta (`evidence_quote`).
`include_answer_text`	Não	Inclui o texto da resposta. Limita a página a 20 linhas.
`max_answer_chars`	Não	Caracteres por resposta quando o texto é incluído (de 200 a 20.000, padrão 1.200).
`limit`, `offset`	Não	Paginação, de 1 a 100 linhas.

get-search-performance

Dados do Google Search Console ou do Bing Webmaster Tools para uma janela.

Argumento	Obrigatório	Significado
`project_id`	Sim	Id do projeto.
`source`	Não	`google` (padrão) ou `bing`.
`period`	Não	`30d` (padrão), `90d`, `365d`.
`dataset`	Não	`summary` (padrão), `top_queries`, `top_pages`, `top_countries`, `queries_by_country`, `opportunities`, `trends`, `ai_question_queries` (só Google), `daily`, `history`.
`query_contains`, `page_contains`, `country`	Não	Filtros de texto nos conjuntos de dados em lista.
`min_impressions`, `min_clicks`, `min_position`, `max_position`	Não	Filtros numéricos.
`sort`	Não	`clicks` (padrão), `impressions`, `ctr`, `position`.
`limit`, `offset`	Não	Paginação dos conjuntos de dados em lista.

As listas trazem a amostra principal armazenada (até 50 linhas por dimensão e até 1.000 consultas em forma de pergunta) e não são uma exportação completa. history soma a série diária por mês do calendário.

get-competitors

Argumento	Obrigatório	Significado
`project_id`	Sim	Id do projeto.
`period`	Não	Período do relatório.
`dataset`	Não	`ranking` (padrão), `detail`, `history`.
`competitor`	Para `detail`	Nome da marca ou parte dele.
`include_highlights`, `highlights_per_platform`	Não	Frases de destaque por plataforma no ranking (padrão 3, máximo 5).
`limit`, `offset`	Não	Linhas do `ranking` (máximo 50) ou meses do `history`.

ranking devolve uma linha por marca no período, incluindo a própria marca, em ordem de visibilidade. history devolve os snapshots armazenados mês a mês.

get-citations

Argumento	Obrigatório	Significado
`project_id`	Sim	Id do projeto.
`period`	Não	Período do relatório.
`group_by`	Não	`url` (padrão) ou `domain`.
`platform`, `prompt_id`, `url_contains`	Não	Filtros para o agrupamento por URL.
`own_site_only`	Não	Só URLs do site do projeto.
`limit`, `offset`	Não	Paginação.

get-ai-traffic

Argumento	Obrigatório	Significado
`project_id`	Sim	Id do projeto.
`period`	Não	`30d` (padrão), `90d`, `365d`.
`dataset`	Não	`summary` (padrão), `sources`, `landing_pages`, `daily`, `history`.
`source`	Não	Uma única fonte de IA (`chatgpt`, `gemini`, `perplexity`, `claude`, `copilot`, `meta_ai`, `other_ai_assistants`, `ai_overviews`).
`path_contains`	Não	Filtro nos caminhos das páginas de destino.
`limit`, `offset`	Não	Paginação de `landing_pages`.

get-project-data

Vários conjuntos de dados em uma só chamada. Sem sections, a ferramenta devolve um perfil de visão geral compacto com todos os conjuntos de dados, exceto ai_visibility.summary, que repete os outros: 10 linhas por lista, o snapshot de 30 dias de cada fonte conectada e nenhum texto de resposta.

Argumento	Obrigatório	Significado
`project_id`	Sim	Id do projeto.
`sections`	Não	Identificadores de conjuntos de dados (abaixo).
`period`	Não	Período do relatório para as seções de visibilidade em IA.
`limit`, `offset`	Não	Linhas por seção paginada, de 1 a 100 (padrão 25).
`include_answer_text`	Não	Texto das respostas em `ai_visibility.mentions` (máximo de 20 linhas).

Identificadores de conjuntos de dados

Identificador	Conteúdo
`ai_visibility.summary`	O mesmo panorama de `get-project-summary`. Só é devolvido quando pedido pelo nome.
`ai_visibility.metrics`	KPIs de visibilidade ao vivo para o período: pontuação, menções por plataforma, citações, posição média, variação em relação ao período anterior, share of voice.
`ai_visibility.answer_insights`	Resumo das avaliações das respostas no período.
`ai_visibility.search_queries`	Buscas na web que as plataformas de IA fizeram para cada pergunta dos clientes.
`ai_visibility.topics`	Temas com o número de perguntas de cada um.
`ai_visibility.prompts`	Perguntas dos clientes e a frequência de monitoramento de cada uma (sugestões inativas do onboarding ficam ocultas).
`ai_visibility.mentions`	Respostas armazenadas com avaliações, como em `get-ai-answers`.
`citations.top_sites`	Domínios mais citados no período.
`citations.urls`	URLs citadas no período, agrupadas por URL.
`competitors`	Concorrentes agregados no período, incluindo a própria marca.
`recommendations`	Artigos de recomendações armazenados (markdown).
`trust_mentions`	Menções históricas em plataformas de avaliações. Não são mais coletadas.
`ga4.ai_traffic`	Snapshots do GA4, o mais recente de cada janela.
`google_search_console.performance`	Snapshots do Search Console, o mais recente de cada janela, sem a série diária.
`bing_webmaster_tools.performance`	Snapshots do Bing, o mais recente de cada janela, sem a série diária.
`project.business_profile`	O perfil do negócio e o contexto de onboarding do projeto.
`history`	Histórico mensal: visibilidade a partir dos snapshots de concorrentes, cliques e impressões do Google e do Bing, sessões de IA do GA4.
`connections`	Estado das conexões do GA4, do Search Console e do Bing.

Paginação

Os conjuntos de dados paginados devolvem offset, limit, returned, total e has_more. Quando has_more for true, peça a próxima página com um offset maior. Pedir um conjunto de dados por vez deixa a paginação mais simples.

Tamanho e atualidade

Cada resposta é um único documento JSON. O resumo do projeto fica em torno de 16 KB e o plano de ação em até cerca de 24 KB; com os limites padrão, as ferramentas específicas e as seções individuais ficam em até cerca de 40 KB. Confira period, fetched_at e is_stale antes de combinar números de conjuntos de dados diferentes.

Um erro de autenticação pede uma nova conexão. Um erro de projeto não encontrado indica um id errado ou um projeto fora da conta autorizada. Conjuntos de dados e seções desconhecidos e valores fora do intervalo são rejeitados. Estas ferramentas não atualizam serviços externos nem alteram projetos. Leia sobre as atualizações de dados.