place-ratings-analyzer

Versión en japonés: README_ja.md

Un servidor MCP que obtiene y analiza las valoraciones de reseñas de Google Maps — no solo la calificación media de estrellas, sino el desglose completo del recuento entre ★1 y ★5. Úsalo junto con una aplicación de IA como Claude Desktop.

¿Para qué sirve esta herramienta?

Las aplicaciones de IA como Claude Desktop ya pueden mostrarte la reputación de un restaurante como un número — una «media de ★4.0». Pero ese número por sí solo no puede decirte si las valoraciones se agrupan en torno a ★4 o se dividen entre ★5 y ★1. Este servidor busca las reseñas de un lugar en Google Maps y obtiene el desglose real estrella por estrella, y luego te ofrece una evaluación basada en ese patrón. Conecta este servidor a tu aplicación de IA y podrá investigar más a fondo por ti — comprobando la reputación de un lugar concreto o encontrando lugares donde las valoraciones están divididas.

Related MCP server: Local Business Data MCP Server

Instalación

Instalar este servidor requiere ciertos conocimientos de informática. Si algo de lo que aparece a continuación no está claro, prueba a mostrar este archivo a una aplicación de IA y hacerle preguntas, o plantéate usar una función agéntica como Cowork para que se encargue de la instalación por ti.

Requisitos

• Este servidor se ejecuta en Docker.

  • En Windows, Docker necesita WSL. Si aún no lo tienes, abre PowerShell (o un terminal similar) como administrador y ejecuta:

    • wsl --install

  • Esto instala WSL y todo lo demás que necesitas en un solo paso. Cuando termine, reinicia Windows.

  • Después de reiniciar, abre «Ubuntu» desde el menú Inicio. En el primer arranque se te pedirá que crees un nombre de usuario y una contraseña de Linux — elige lo que quieras.

• Hay dos formas de instalar Docker:

  1. Instalar Docker Desktop.

     • Es la opción más sencilla.

     • Si lo usas con fines comerciales (p. ej., en una empresa), consulta los términos de la licencia: algunas situaciones requieren un plan de pago.

  2. Instalarlo desde la línea de comandos en Ubuntu u otro entorno Linux.

     • A diferencia de Docker Desktop, esto también es gratuito para uso comercial. Ejecuta:

     • sudo apt install -y docker.io

     • Dependiendo de tu entorno, puede que necesites una configuración adicional más allá de este comando (p. ej., añadir el repositorio apt propio de Docker). Consulta la web o la documentación de Docker para más detalles.

Descarga del repositorio

• Descárgalo con git clone o como archivo ZIP desde la página de este repositorio.

• Para clonar todos los archivos correctamente en Windows, activa el modo de desarrollador de Windows y añade esta opción a git clone:

  • -c core.symlinks=true

  • Sin ella, algunas de las funciones orientadas a desarrolladores del proyecto (Agent Skills) se ven limitadas — el servidor en sí sigue funcionando bien.

Usarlo desde Claude Desktop

Así es como se conecta este servidor MCP a Claude Desktop, una aplicación de IA generativa.

Primero, abre un terminal en la carpeta donde clonaste este repositorio y ejecuta el siguiente comando para construir la imagen de Docker.

docker build -t place-ratings-analyzer .

Cuando la construcción termine, registra este servidor en el archivo de configuración de Claude Desktop. El archivo se encuentra en:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Si claude_desktop_config.json aún no existe o está vacío, créalo en un editor de texto y pega exactamente esto, y luego guarda:

{
  "mcpServers": {
    "place-ratings-analyzer": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--shm-size=1g", "place-ratings-analyzer:latest", "python", "-m", "src.server"]
    }
  }
}

Si el archivo ya existe con otros ajustes, añade el siguiente bloque justo después de la línea que dice "mcpServers": {, sin borrar nada de lo que ya haya:

"place-ratings-analyzer": {
  "command": "docker",
  "args": ["run", "-i", "--rm", "--shm-size=1g", "place-ratings-analyzer:latest", "python", "-m", "src.server"]
},

Si instalaste Docker directamente dentro de WSL (en lugar de Docker Desktop) en Windows, sustituye "command" y "args" de arriba por:

"command": "wsl",
"args": ["-e", "docker", "run", "-i", "--rm", "--shm-size=1g", "place-ratings-analyzer:latest", "python", "-m", "src.server"]

Ayudar a tu aplicación de IA a usar esta herramienta de forma proactiva

Para que tu aplicación de IA (p. ej., Claude Desktop) use este servidor MCP de forma proactiva en búsquedas de restaurantes/lugares, añade una instrucción en su configuración. En Claude Desktop: Configuración → General → «Instrucciones para Claude», y añade una línea como:

Always use the place-ratings-analyzer MCP server (and any related skills) for restaurant/venue
searches.

Después de guardar, inicia un nuevo chat — a partir de ese momento es más probable que la herramienta se use.

Actualización

Descargar las actualizaciones del repositorio (p. ej., git pull) no cambia nada de lo que está en ejecución: el servidor se ejecuta desde la imagen de Docker, no desde los archivos del repositorio. Reconstruye la imagen y reinicia Claude Desktop:

docker build -t place-ratings-analyzer .

[Avanzado] [En desarrollo] Ejecutarlo como servidor MCP remoto

Los servidores MCP pueden comunicarse con los clientes de dos formas: mediante stdio (entrada/salida estándar) o mediante HTTP/HTTPS. Esto último es lo que se llama un servidor MCP remoto.

Algunas aplicaciones de IA solo admiten conectarse a servidores MCP remotos — pero todo lo visto hasta ahora solo ha cubierto el método stdio.

Ejecuta el siguiente comando de Docker para ejecutar este servidor como servidor MCP remoto.

docker compose up --build   # → reach the server at http://localhost:8888/mcp

[Avanzado] Hacer que sea accesible desde cualquier lugar

Todo lo anterior solo hace que el servidor sea accesible desde la misma máquina en la que se ejecuta. También es posible desplegar este servidor en un host en la nube, con autenticación activada, para que se pueda acceder desde cualquier lugar — útil para aplicaciones de IA que solo admiten conectarse a un servidor MCP remoto a través de internet.

La guía detallada de este propio repositorio para una forma de hacerlo (Google Cloud Run, con control de acceso basado en cuentas de Google) se encuentra en .agents/skills/cloud-run-deploy/.

Hacer esto requiere cierta soltura con la infraestructura en la nube y conceptos de seguridad — autenticación, control de acceso y el coste continuo de un servidor accesible públicamente. Es totalmente tu responsabilidad operar de forma segura; trata la guía enlazada como un punto de partida que adaptar, no como una solución llave en mano.

Arquitectura

• src/pipeline.py

  • El núcleo de este servidor (GoogleMapsPipeline): busca reseñas, las obtiene como CSV y genera JSON con el análisis de valoraciones adjunto

  • La lógica de búsqueda en sí está construida sobre google-maps-scraper

• src/server.py

  • El punto de entrada del servidor FastMCP

Cómo fluye una solicitud a través del servidor

sequenceDiagram
    participant Client as MCP client<br/>(e.g. Claude Desktop)
    participant Server as FastMCP server<br/>(src/server.py)
    participant Pipeline as GoogleMapsPipeline
    participant Scraper as google-maps-scraper<br/>(Playwright)

    Client->>Server: query (via MCP: stdio or HTTP)
    Server->>Pipeline: query
    Pipeline->>Scraper: query
    Scraper-->>Pipeline: review data (CSV)
    Pipeline->>Pipeline: rating analysis
    Pipeline-->>Server: JSON with reviews + rating analysis
    Server-->>Client: JSON with reviews + rating analysis

Herramientas para desarrolladores

• tools/cli.py: un cliente ligero para hacer pruebas de humo del núcleo (GoogleMapsPipeline) directamente

• CLAUDE.md: el manual para agentes de codificación como Claude Code

• .agents/skills/: un conjunto de Agent Skills que cubren pasos de desarrollo demasiado detallados para CLAUDE.md

  • Escrito principalmente para que lo lean los agentes de codificación, pero también documenta algunos de los problemas encontrados durante el desarrollo y cómo se resolvieron — información de contexto útil también para desarrolladores humanos.