Referencia de herramientas MCP

Esta referencia está pensada para usuarios que configuran un cliente MCP o revisan qué datos de Searcherries recupera su asistente. El servidor es de solo lectura: lista tus proyectos y lee los datos que Searcherries ya tiene almacenados. Nunca cambia un proyecto y nunca llama a Google, Bing o una plataforma de IA en tu nombre.

Conéctate a https://app.searcherries.com/mcp/searcherries con OAuth autorizado o con un token de acceso personal. Consulta las opciones de conexión.

Orden de llamadas recomendado

Para una petición práctica como «en qué debería trabajar ahora», empieza por get-action-plan. Para una investigación detallada:

list-projects para encontrar el id del proyecto.
get-project-summary para obtener una instantánea compacta de ese proyecto (unos 16 KB).
Una herramienta específica para las filas que necesites: get-ai-answers, get-search-performance, get-competitors, get-citations, get-ai-traffic.
get-project-data cuando quieras varios conjuntos de datos en una sola llamada o una sección heredada.

Los prompts action-plan, geo-audit, content-gaps, competitor-gap, page-brief, question-review y weekly-report contienen estas secuencias como recetas listas para usar. En Claude y Claude Code aparecen en el menú de prompts (comandos de barra) una vez conectado el servidor.

Periodos

Los datos de visibilidad en IA (métricas, respuestas, competidores, citas) usan periodos de informe anclados a la última comprobación completada: last_30_days (por defecto), last_60_days, last_90_days, this_year, last_year. Un periodo sin historial suficiente recurre al más cercano disponible; la respuesta indica qué periodo se usó.

Las fuentes conectadas (Google Search Console, Bing Webmaster Tools, GA4) se almacenan como ventanas móviles que terminan el día de la recopilación: 30d, 90d, 365d. Cada respuesta incluye period_start, period_end, fetched_at e is_stale.

get-action-plan

Los siguientes pasos priorizados de un proyecto. Acepta el nombre o el dominio del proyecto, así que no necesita una llamada previa a list-projects.

Argumento	Obligatorio	Significado
`project`	No	Nombre de la marca, dominio, URL del sitio web o id del proyecto como texto. Omítelo cuando la cuenta tenga un solo proyecto. No lo combines con `project_id`.
`project_id`	No	Un id de proyecto conocido en lugar de `project`.
`audience`	No	`business` (por defecto) para prioridades de tráfico y negocio, `marketing` para respuestas sobre la marca y contenido, `seo` para páginas y consultas de búsqueda.
`period`	No	Periodo de visibilidad en IA. Por defecto `last_30_days`. La búsqueda y el tráfico usan sus propias instantáneas móviles de 30 días.
`limit`	No	Número máximo de acciones, de 1 a 10 (por defecto 5). Se devuelven menos cuando la evidencia es escasa.

La respuesta tiene un status (ready, needs_data, no_priority_signals, o needs_project cuando el proyecto falta o es ambiguo), las actions, las data_notes sobre fuentes ausentes o desactualizadas y un snapshot compacto del proyecto. Cada acción incluye un título, un responsable sugerido, el siguiente paso, evidencia fechada, una medida de éxito, un enlace al informe de Searcherries correspondiente y un next_call con la herramienta y los argumentos que devuelven las filas de apoyo.

Las acciones salen de cuatro señales almacenadas: las respuestas negativas sobre la marca o que nombran un inconveniente, las respuestas en las que no se nombra la marca, las consultas de Search Console y Bing con muchas impresiones y pocos clics, y las páginas de entrada de los visitantes que llegan desde la IA. El orden sigue la audiencia elegida. Es una sugerencia y no estima impacto, esfuerzo ni ingresos. Cuando varios proyectos coinciden con el nombre, la herramienta devuelve los candidatos y el asistente tiene que preguntarte a cuál te refieres.

list-projects

Lista los proyectos de la cuenta autenticada con su estado, las plataformas de IA seguidas, las fuentes conectadas y su frescura, los recuentos de datos almacenados y la fecha de la última comprobación. No recibe argumentos.

get-project-summary

Una instantánea compacta de un proyecto. Bloques: profile (marca, mercado, perfil del negocio), questions (la pregunta principal y las adicionales, con su última y su próxima comprobación), ai_visibility (puntuación, menciones por plataforma, cambio frente al periodo anterior, cuota de voz), answer_insights (con qué frecuencia y protagonismo se nombra la marca, respuestas negativas y fuera de tema), competitors (la marca propia y los 10 principales), citations (dominios más citados), search (totales de 30 días de Google y Bing con listas de los 5 principales), ai_traffic (tráfico de IA de GA4 de 30 días con sesiones con interacción, eventos clave, conversiones y la cuota sobre todas las sesiones del sitio), connections (estado de las conexiones) y recommendations (último resumen).

Argumento	Obligatorio	Significado
`project_id`	Sí	Id del proyecto obtenido de `list-projects`.
`period`	No	Periodo de visibilidad en IA. Por defecto `last_30_days`.
`include`	No	Bloques que incluir; omítelo para todos.

get-ai-answers

Respuestas de IA almacenadas, una fila por comprobación y plataforma, unidas a sus valoraciones: prominence_level (0 no nombrada, 1 nombrada de pasada, 2 una de las opciones, 3 recomendación principal), on_topic, names_brands, brand_sentiment, brand_drawback, evidence_quote, las URL citadas y las búsquedas web que hizo la plataforma. brand_mentioned es null en las respuestas que el proceso nocturno de valoración aún no ha evaluado.

Argumento	Obligatorio	Significado
`project_id`	Sí	Id del proyecto.
`period`	No	Periodo del informe; se ignora cuando se indican `since`/`until`.
`since`, `until`	No	Fechas de comprobación, `YYYY-MM-DD`.
`prompt_id`	No	Una pregunta de cliente.
`platform`	No	Una plataforma de IA.
`prominence_max`	No	Conserva las respuestas con un protagonismo igual o inferior a este nivel. `1` lista los huecos.
`only_flagged`	No	Solo respuestas negativas, con inconveniente o fuera de tema.
`include_answer_text`	No	Incluye el texto de la respuesta. Limita la página a 20 filas.
`max_answer_chars`	No	Caracteres por respuesta cuando se incluye el texto (de 200 a 20000, por defecto 1200).
`limit`, `offset`	No	Paginación, de 1 a 100 filas.

get-search-performance

Datos de Google Search Console o Bing Webmaster Tools para una ventana.

Argumento	Obligatorio	Significado
`project_id`	Sí	Id del proyecto.
`source`	No	`google` (por defecto) o `bing`.
`period`	No	`30d` (por defecto), `90d`, `365d`.
`dataset`	No	`summary` (por defecto), `top_queries`, `top_pages`, `top_countries`, `queries_by_country`, `opportunities`, `trends`, `ai_question_queries` (solo Google), `daily`, `history`.
`query_contains`, `page_contains`, `country`	No	Filtros de texto sobre los conjuntos de datos de lista.
`min_impressions`, `min_clicks`, `min_position`, `max_position`	No	Filtros numéricos.
`sort`	No	`clicks` (por defecto), `impressions`, `ctr`, `position`.
`limit`, `offset`	No	Paginación para los conjuntos de datos de lista.

Las listas son la muestra principal almacenada (hasta 50 filas por dimensión y hasta 1000 consultas con forma de pregunta), no una exportación exhaustiva. history suma la serie diaria por mes natural.

get-competitors

Argumento	Obligatorio	Significado
`project_id`	Sí	Id del proyecto.
`period`	No	Periodo del informe.
`dataset`	No	`ranking` (por defecto), `detail`, `history`.
`competitor`	Para `detail`	Nombre de la marca o un fragmento.
`include_highlights`, `highlights_per_platform`	No	Frases destacadas por plataforma en el ranking (por defecto 3, máximo 5).
`limit`, `offset`	No	Filas para `ranking` (máximo 50) o meses para `history`.

ranking devuelve una fila por marca para el periodo, incluida la propia, ordenadas por visibilidad. history devuelve las instantáneas almacenadas mes a mes.

get-citations

Argumento	Obligatorio	Significado
`project_id`	Sí	Id del proyecto.
`period`	No	Periodo del informe.
`group_by`	No	`url` (por defecto) o `domain`.
`platform`, `prompt_id`, `url_contains`	No	Filtros para la agrupación por URL.
`own_site_only`	No	Solo las URL del sitio web del proyecto.
`limit`, `offset`	No	Paginación.

get-ai-traffic

Argumento	Obligatorio	Significado
`project_id`	Sí	Id del proyecto.
`period`	No	`30d` (por defecto), `90d`, `365d`.
`dataset`	No	`summary` (por defecto), `sources`, `landing_pages`, `daily`, `history`.
`source`	No	Una fuente de IA (`chatgpt`, `gemini`, `perplexity`, `claude`, `copilot`, `meta_ai`, `other_ai_assistants`, `ai_overviews`).
`path_contains`	No	Filtro sobre las rutas de las páginas de entrada.
`limit`, `offset`	No	Paginación para `landing_pages`.

get-project-data

Varios conjuntos de datos en una sola llamada. Si se omite sections, devuelve un perfil de resumen compacto con todos los conjuntos de datos excepto ai_visibility.summary, que repite los demás: 10 filas por lista, la instantánea de 30 días de cada fuente conectada y sin texto de respuestas.

Argumento	Obligatorio	Significado
`project_id`	Sí	Id del proyecto.
`sections`	No	Identificadores de conjuntos de datos (abajo).
`period`	No	Periodo del informe para las secciones de visibilidad en IA.
`limit`, `offset`	No	Filas por sección paginada, de 1 a 100 (por defecto 25).
`include_answer_text`	No	Texto de las respuestas en `ai_visibility.mentions` (máximo 20 filas).

Identificadores de conjuntos de datos

Identificador	Contenido
`ai_visibility.summary`	La misma instantánea que `get-project-summary`. Solo se devuelve si se pide por su nombre.
`ai_visibility.metrics`	KPI de visibilidad en vivo para el periodo: puntuación, menciones por plataforma, citas, posición media, cambio frente al periodo anterior, cuota de voz.
`ai_visibility.answer_insights`	Resumen de las valoraciones de las respuestas del periodo.
`ai_visibility.search_queries`	Búsquedas web que hicieron las plataformas de IA por pregunta de cliente.
`ai_visibility.topics`	Temas con su número de preguntas.
`ai_visibility.prompts`	Preguntas de clientes y su frecuencia de seguimiento (las sugerencias inactivas del onboarding se ocultan).
`ai_visibility.mentions`	Respuestas almacenadas con valoraciones, como en `get-ai-answers`.
`citations.top_sites`	Dominios más citados del periodo.
`citations.urls`	URL citadas del periodo, agrupadas por URL.
`competitors`	Competidores agregados para el periodo, incluida la marca propia.
`recommendations`	Artículos de recomendaciones almacenados (markdown).
`trust_mentions`	Menciones históricas en plataformas de reseñas. Ya no se recopilan.
`ga4.ai_traffic`	Instantáneas de GA4, la más reciente por ventana.
`google_search_console.performance`	Instantáneas de Search Console, la más reciente por ventana, sin la serie diaria.
`bing_webmaster_tools.performance`	Instantáneas de Bing, la más reciente por ventana, sin la serie diaria.
`project.business_profile`	El perfil del negocio y el contexto de onboarding del proyecto.
`history`	Historial mensual: visibilidad a partir de las instantáneas de competidores, clics e impresiones de Google y Bing, sesiones de IA de GA4.
`connections`	Estado de las conexiones de GA4, Search Console y Bing.

Paginación

Los conjuntos de datos paginados devuelven offset, limit, returned, total y has_more. Cuando has_more es true, solicita la página siguiente con un offset mayor. Pedir un conjunto de datos cada vez simplifica la paginación.

Tamaño y frescura

Las respuestas son documentos JSON únicos. El resumen del proyecto ronda los 16 KB y el plan de acción se queda dentro de unos 24 KB; las herramientas específicas y las secciones individuales se quedan dentro de unos 40 KB con los límites por defecto. Comprueba period, fetched_at e is_stale antes de combinar cifras de conjuntos de datos distintos.

Un error de autenticación requiere volver a conectar. Un error de proyecto no encontrado significa un id incorrecto o un proyecto fuera de la cuenta autorizada. Los conjuntos de datos y secciones desconocidos y los valores fuera de rango se rechazan. Estas herramientas no actualizan servicios externos ni modifican proyectos. Más información sobre las actualizaciones de datos.