Servidor MCP no oficial de Google Trends

⚠️ Proyecto no oficial. No está afiliado, respaldado ni soportado por Google. Google Trends no tiene una API pública disponible de forma general, por lo que este servidor lee los mismos endpoints de acceso público que usa el sitio web trends.google.com (a través de trendspy) — lo que significa que Google puede limitar la velocidad o romperlo en cualquier momento, sin previo aviso. Úsalo bajo tu propio riesgo y lee Limitaciones antes de confiar en él.

Un servidor de Model Context Protocol que brinda a los asistentes de IA — Claude, ChatGPT, Cursor o cualquier cliente MCP — acceso a los datos de Google Trends: interés de búsqueda a lo largo del tiempo, desgloses regionales, búsquedas en tendencia e ideas de palabras clave.

Funciona como un servidor MCP remoto (HTTP transmisible) diseñado para Google Cloud Run — lo alojas en tu propio proyecto de Google Cloud y lo conectas al asistente de IA que elijas. También funciona localmente mediante stdio.

Conéctalo a tu asistente de IA

Después de implementarlo (consulta Configuración), tendrás una URL de endpoint como https://<tu-servicio>.run.app/<secreto>/mcp. Todas las herramientas son de solo lectura.

Claude (web/escritorio): Configuración → Conectores → Agregar conector personalizado → pega la URL. Funciona en los planes Pro, Max, Team y Enterprise.

ChatGPT (web): activa el modo Desarrollador (Configuración → Aplicaciones → Configuración avanzada), luego Configuración → Aplicaciones → Crear, pega la URL como endpoint del servidor MCP, elige Sin autenticación (el control de acceso es el secreto en la URL), haz clic en Escanear herramientas → Crear. Los conectores MCP personalizados requieren un plan de pago; en Pro, los conectores se limitan a herramientas de solo lectura — que es todo lo que tiene este servidor, así que funciona.

Claude Code / Cursor / otros clientes MCP: cualquier cliente que admita MCP remoto sobre HTTP transmisible funciona, por ejemplo claude mcp add --transport http google-trends <URL>. Para configuraciones locales/stdio consulta docs/setup-advanced.md.

Related MCP server: youtube-trends-mcp

Cómo funciona

AI assistant (Claude · ChatGPT · Cursor · any MCP client)
   │  MCP over streamable HTTP, at https://<cloud-run-url>/<secret>/mcp
   ▼
server.py — FastMCP tool layer (stateless, JSON responses)
   │  TrendsBackend interface (swappable, see backends/)
   ▼
backends/trendspy_backend.py
   │  1. TTL cache — identical queries answered from memory
   │     (12 h series · 15 min trending · 24 h autocomplete)
   │  2. Circuit breaker — after a 429: cooldown, fail fast with
   │     a clear "retry in Ns" message (no hammering Google)
   │  3. One upstream call at a time, ≥3 s apart
   ▼
Google's public endpoints
   ├─ trends.google.com (unofficial, same as the website uses)
   └─ suggestqueries.google.com (Autocomplete, for keyword_ideas)

El control de acceso es un segmento de ruta secreto aleatorio en la URL (generado en la implementación, almacenado en un archivo .mcp_secret ignorado por git) — se usa porque la mayoría de las interfaces de conectores personalizados de los clientes de chat (Claude, ChatGPT) no pueden enviar encabezados de autenticación. El servicio de Cloud Run está limitado a una instancia a propósito: una instancia = una IP y una caché compartida, lo que mantiene predecible la limitación de velocidad de Google. Se reduce a cero cuando está inactivo, por lo que el alojamiento es ~gratis para uso personal.

Herramientas

Backends de datos

La capa de datos es intercambiable (consulta backends/):

• trendspy (predeterminado) — usa trendspy, que se comunica con los mismos endpoints no oficiales que el sitio web de Trends. Gratis, sin clave de API, pero limitado por IP y podría romperse si Google cambia sus endpoints.

• official (stub) — para la API oficial de Trends de Google (alfa), que está restringida por solicitud de aplicación. Conecta backends/official_backend.py una vez que Google otorgue acceso a tu proyecto, luego establece TRENDS_BACKEND=official. El contrato de la herramienta MCP permanece idéntico.

⚠️ Los valores de Google Trends son interés de búsqueda relativo (0–100 dentro de cada consulta), no volúmenes de búsqueda absolutos.

Configuración

Dos guías, elige tu ritmo:

• Guía para principiantes — ¿nunca usaste una terminal o Google Cloud? Recorrido completo desde cero, ~15 minutos.

• Guía avanzada — ¿experimentado? Clona → ./deploy.sh → conecta; además modo local stdio, referencia de configuración y notas de arquitectura.

Implementar en Cloud Run (versión rápida)

gcloud auth login
./deploy.sh YOUR_PROJECT_ID europe-west1

El script habilita las API requeridas, compila el contenedor con Cloud Build, implementa con escala a cero (≈ gratis con uso bajo) e imprime tu endpoint MCP:

https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

El segmento aleatorio <secreto> en la ruta es el token de acceso — el servicio es técnicamente público, pero inalcanzable sin la URL completa. Mantenlo privado y vuelve a ejecutar la implementación con un nuevo secreto para rotarlo.

Conecta tu asistente de IA

Consulta Conéctalo a tu asistente de IA arriba para Claude y ChatGPT. Claude Code:

claude mcp add --transport http google-trends https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

Ejecutar localmente

pip install -r requirements.txt
python server.py
# MCP endpoint at http://localhost:8080/mcp

Configuración

Limitaciones y problemas conocidos

Lee esto antes de confiar en el servidor — son estructurales, no errores:

1. Fuente de datos no oficial. No existe una API pública de Google Trends (la API oficial de Google es alfa y solo por invitación). Este servidor usa los endpoints del propio sitio web, que Google puede cambiar o bloquear en cualquier momento. Si Google cambia algo, el servidor se rompe hasta que trendspy se ponga al día — exactamente lo que le pasó a la biblioteca anterior pytrends en 2025.

2. related_queries y related_topics están efectivamente muertos. Google impone una cuota casi nula en estos dos endpoints de "widget" para clientes automatizados (no navegador). El límite es por huella del cliente, no por IP — los proxies, VPN y ejecutar localmente no ayudan. Espera que estas herramientas fallen en la primera llamada la mayoría de las veces; el mensaje de error lo dice y apunta a keyword_ideas (Google Autocomplete), que es la alternativa confiable para investigación de palabras clave.

3. Límites de velocidad en todo lo demás. Los endpoints que funcionan (interés a lo largo del tiempo, por región, tendencias) también están limitados por IP. Las ráfagas de solicitudes provocan HTTP 429. Las mitigaciones del servidor (abajo) hacen que esto sea raro en uso normal, pero las consultas automatizadas intensas chocarán con el muro.

4. Valores relativos, no volúmenes. Todos los números de Trends son 0–100 dentro de cada consulta (100 = el pico para ese conjunto de términos/período/geo). No son volúmenes de búsqueda absolutos y no son comparables entre consultas separadas.

5. Compensación de frescura. Los resultados se almacenan en caché (12 h para datos de series, 15 min para tendencias, 24 h para autocompletado) para mantenerse bajo los límites de velocidad — puedes ver datos ligeramente desactualizados por diseño.

6. Instancia única. Implementado con --max-instances 1, por lo que es para uso personal/equipos pequeños, no para tráfico de producción de alta concurrencia.

Límites de velocidad y cómo está diseñado el servidor en torno a ellos

Google limita la velocidad de los endpoints no oficiales de Trends. El servidor mitiga esto en capas:

• Caché TTL — las consultas idénticas se sirven desde la memoria (~12h para datos de series, 15 min para tendencias, 24h para autocompletado) y nunca llegan a Google dos veces.

• Espaciado + serialización — una llamada ascendente a la vez, con una pausa de TRENDS_REQUEST_DELAY (predeterminado 3s) entre llamadas.

• Reintento + interruptor de circuito — un reintento suave en un 429, luego un período de enfriamiento (120s) durante el cual las nuevas consultas fallan rápidamente con un mensaje claro de "reintenta en Ns" en lugar de golpear a Google. Las consultas en caché siguen funcionando durante los períodos de enfriamiento.

• Reglas de uso empujadas al cliente de IA mediante instrucciones MCP: agrupa hasta 5 términos por llamada interest_over_time, planifica las llamadas en lugar de dispersarlas, nunca reintentes automáticamente un error de límite de velocidad.

• Realidad de related_queries / related_topics: Google ha reducido estos dos endpoints de widget a cuota casi nula para clientes automatizados (no navegador) — esto es por huella, por lo que los proxies y cambios de IP no ayudan. Espera que fallen; el error lo explica. Usa keyword_ideas (Google Autocomplete) para investigación de palabras clave en su lugar — es rápido, confiable y no está sujeto a la cuota de Trends.

--max-instances 1 en el script de implementación es intencional: una instancia = una IP y una caché compartida = limitación de velocidad predecible.

Consejos para usuarios

Pide comparaciones de una sola vez ("compara A vs B vs C en PT durante 12 meses" → una llamada a la API) en lugar de un término a la vez. Las repeticiones de preguntas recientes son gratuitas (caché). Si encuentras un mensaje de enfriamiento, solo espera los segundos indicados — no envíes reintentos en ráfaga. Para "qué busca la gente en torno a X", pide ideas de palabras clave en lugar de consultas relacionadas.

Notas de seguridad

Todo en este repositorio es genérico — sin credenciales, claves, IDs de proyecto ni datos personales. Dos cosas permanecen locales en tu máquina y nunca deben ser confirmadas:

• .mcp_secret — la cadena aleatoria en tu URL de endpoint. Es lo único que impide que extraños llamen a tu servidor implementado, así que trátalo como una contraseña. deploy.sh lo genera en la primera ejecución y lo mantiene aquí para que las reimplementaciones reutilicen la misma URL. Está en gitignore. (No está relacionado con GitHub — no es un token de GitHub y no tiene acceso a tu cuenta).

• Tu ID de proyecto de Google Cloud — se pasa como argumento de línea de comandos a deploy.sh, nunca se escribe en ningún archivo del repositorio.

Para rotar el secreto (por ejemplo, si la URL se filtró): elimina .mcp_secret, vuelve a ejecutar ./deploy.sh <PROJECT_ID> y actualiza la URL en la configuración del conector de tu asistente de IA. La URL anterior deja de funcionar inmediatamente.

Antes de tu primer push, confirma que no hay nada sensible en el área de preparación:

git status --short          # .mcp_secret and .env must NOT appear
git check-ignore -v .mcp_secret

Descargo de responsabilidad

Proyecto comunitario no oficial; no está afiliado, respaldado ni soportado por Google. "Google Trends" y "Google" son marcas comerciales de Google LLC, usadas aquí solo para describir a qué se conecta el software. Los datos de Trends se obtienen a través de endpoints de acceso público; eres responsable de usarlos de acuerdo con los términos de servicio de Google y bajo tu propio riesgo. Sin garantía de ningún tipo — los endpoints pueden dejar de funcionar en cualquier momento.

Licencia

MIT