place-ratings-analyzer

Japanische Version: README_ja.md

Ein MCP-Server, der Google-Maps-Bewertungen abruft und analysiert – nicht nur die durchschnittliche Sternebewertung, sondern die vollständige Aufschlüsselung der Anzahl über ★1–★5. Verwenden Sie ihn zusammen mit einer KI-App wie Claude Desktop.

Wofür ist dieses Tool da?

KI-Apps wie Claude Desktop können Ihnen bereits die Reputation eines Restaurants als Zahl zeigen – eine "★4,0-Durchschnittsbewertung". Aber diese Zahl allein kann nicht sagen, ob sich die Bewertungen um ★4 gruppieren oder zwischen ★5 und ★1 aufteilen. Dieser Server sucht die Bewertungen eines Ortes auf Google Maps und erhält die tatsächliche Aufschlüsselung nach Sternen, dann gibt er eine Einschätzung basierend auf diesem Muster. Verbinden Sie diesen Server mit Ihrer KI-App, und sie kann für Sie tiefergehend recherchieren – die Reputation eines bestimmten Ortes prüfen oder Orte finden, bei denen die Bewertungen gespalten sind.

Related MCP server: Local Business Data MCP Server

Installation

Die Installation dieses Servers erfordert etwas Computererfahrung. Wenn etwas oben unklar ist, versuchen Sie, dieses File einer KI-App zu zeigen und Fragen zu stellen, oder erwägen Sie die Nutzung einer agentischen Funktion wie Cowork, um die Installation für Sie zu übernehmen.

Voraussetzungen

• Dieser Server läuft auf Docker.

  • Unter Windows benötigt Docker WSL. Falls Sie es noch nicht haben, öffnen Sie PowerShell (oder ein ähnliches Terminal) als Administrator und führen Sie Folgendes aus:

    • wsl --install

  • Dadurch werden WSL und alles andere Nötige in einem Schritt installiert. Starten Sie anschließend Windows neu.

  • Öffnen Sie nach dem Neustart "Ubuntu" aus dem Startmenü. Beim ersten Start werden Sie aufgefordert, einen Linux-Benutzernamen und ein Passwort zu erstellen — wählen Sie, was Ihnen gefällt.

• Es gibt zwei Möglichkeiten, Docker selbst zu installieren:

  1. Installieren Sie Docker Desktop.

     • Dies ist der einfachere Weg.

     • Wenn Sie es kommerziell nutzen (z. B. in einem Unternehmen), prüfen Sie Ihre Lizenzbedingungen – einige Situationen erfordern einen kostenpflichtigen Plan.

  2. Installieren Sie es über die Befehlszeile auf Ubuntu oder einer anderen Linux-Umgebung.

     • Anders als Docker Desktop ist dies auch für die kommerzielle Nutzung kostenlos. Führen Sie aus:

     • sudo apt install -y docker.io

     • Je nach Umgebung sind möglicherweise zusätzliche Schritte erforderlich (z. B. das Hinzufügen des eigenen apt-Repository von Docker). Details finden Sie im Web oder in der Docker-Dokumentation.

Note: The list items are nested, we need to preserve that.

Continue.

After that, "### Downloading the repository" etc.

We'll translate all prose.

Remember to keep all code blocks, inline code, links, names, etc.

Let's do it step by step.

I'll write the translation.# place-ratings-analyzer

Japanische Version: README_ja.md

Ein MCP-Server, der Google-Maps-Bewertungen abruft und analysiert – nicht nur die durchschnittliche Sternebewertung, sondern die vollständige Anzahl-Aufschlüsselung über ★1–★5. Verwenden Sie ihn zusammen mit einer KI-App wie Claude Desktop.

Wofür ist dieses Tool gedacht?

KI-Apps wie Claude Desktop können Ihnen bereits die Reputation eines Restaurants als Zahl anzeigen – etwa einen "★4,0-Durchschnitt". Aber diese Zahl allein kann nicht sagen, ob sich die Bewertungen um ★4 gruppieren oder zwischen ★5 und ★1 aufteilen. Dieser Server ruft die Bewertungen eines Ortes auf Google Maps ab und erhält die tatsächliche Aufschlüsselung nach Sternen, dann gibt er eine Einschätzung basierend auf diesem Muster aus. Wenn Sie diesen Server mit Ihrer KI-App verbinden, kann sie für Sie tiefergehend recherchieren – die Reputation eines bestimmten Ortes überprüfen oder Orte finden, bei denen die Bewertungen gespalten sind.

Installation

Die Installation dieses Servers erfordert etwas Computererfahrung. Falls etwas oben unklar ist, versuchen Sie, diese Datei einer KI-App zu zeigen und Fragen zu stellen, oder erwägen Sie die Nutzung einer agentischen Funktion wie „Cowork", um die Installation für Sie zu übernehmen.

Voraussetzungen

• Dieser Server läuft auf Docker.

  • Unter Windows benötigt Docker WSL. Falls Sie es noch nicht haben, öffnen Sie PowerShell (oder ein ähnliches Terminal) als Administrator und führen Sie aus:

    • wsl --install

  • Dadurch werden WSL und alles andere Nötige in einem Schritt installiert. Starten Sie anschließend Windows neu.

  • Nach dem Neustart öffnen Sie "Ubuntu" aus dem Startmenü. Beim ersten Start werden Sie aufgefordert, einen Linux-Benutzernamen und ein Passwort zu erstellen – wählen Sie, was Ihnen gefällt.

• Es gibt zwei Möglichkeiten, Docker selbst zu installieren:

  1. Installieren Sie Docker Desktop.

     • Das ist der einfachere Weg.

     • Wenn Sie es kommerziell nutzen (z. B. in einem Unternehmen), prüfen Sie Ihre Lizenzbedingungen – einige Situationen erfordern einen kostenpflichtigen Plan.

  2. Installieren Sie es über die Befehlszeile auf Ubuntu oder einer anderen Linux-Umgebung.

     • Anders als Docker Desktop ist dies auch für die kommerzielle Nutzung kostenlos. Führen Sie aus:

     • sudo apt install -y docker.io

     • Je nach Umgebung können zusätzliche Schritte erforderlich sein (z. B. das Hinzufügen des offiziellen Docker-apt-Repositorys). Weitere Details finden Sie im Web oder in der Docker-Dokumentation.

Repository herunterladen

• Laden Sie es entweder mit git clone oder als ZIP-Datei von der Repository-Seite herunter.

• Um jeden Ordner unter Windows korrekt zu klonen, aktivieren Sie den Windows-Entwicklermodus und fügen Sie diese Option zu git clone hinzu:

  • -c core.symlinks=true

  • Ohne diese Option sind einige entwicklungsorientierte Funktionen des Projekts (Agent Skills) eingeschränkt – der Server selbst funktioniert trotzdem einwandfrei.

Verwendung mit Claude Desktop

So verbinden Sie diesen Server mit Claude Desktop, einer generativen KI-App.

Öffnen Sie zuerst ein Terminal in dem Ordner, in den Sie dieses Repository geklont haben, und führen Sie den folgenden Befehl aus, um das Docker-Image zu erstellen.

docker build -t place-ratings-analyzer .

Wenn der Build abgeschlossen ist, registrieren Sie diesen Server in der Konfigurationsdatei von Claude Desktop. Die Datei befindet sich unter:

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

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

Falls claude_desktop_config.json noch nicht existiert oder leer ist, erstellen Sie sie in einem Texteditor und fügen Sie genau dies ein, dann speichern:

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

Falls die Datei bereits existiert und andere Einstellungen enthält, fügen Sie den folgenden Block direkt nach "mcpServers": { ein, ohne vorhandene Einträge zu löschen:

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

Wenn Sie Docker direkt in WSL installiert haben (nicht Docker Desktop) unter Windows, ersetzen Sie „command" und „args" durch Folgendes:

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

Damit Ihre KI-App dieses Tool proaktiv nutzt

Damit Ihre KI-App (z. B. Claude Desktop) diesen MCP-Server proaktiv bei Orts-/Restaurantsuchen verwendet, fügen Sie eine Anweisung in ihren Einstellungen hinzu. Gehen Sie in Claude Desktop zu Einstellungen → „Anweisungen für Claude" (oder Ähnliches) und fügen Sie eine Zeile wie diese hinzu:

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

Aktualisierung

Wenn Sie Updates aus dem Repository ziehen (z. B. git pull), ändert sich nichts am laufenden Server – er läuft aus dem Docker-Image. Bauen Sie das Image neu und starten Sie Claude Desktop neu:

docker build -t place-ratings-analyzer .

[Fortgeschritten] [In Entwicklung] Als Remote-MCP-Server ausführen

MCP-Server können auf zwei Arten mit Clients kommunizieren: über stdio (Standard-Eingabe/Ausgabe) oder über HTTP/HTTPS. Letzteres nennt man Remote-MCP-Server.

Manche KI-Apps unterstützen nur die Verbindung zu Remote-MCP-Servern – aber alles bisher Beschriebene betraf nur die stdio-Methode.

Führen Sie den folgenden Docker-Befehl aus, um diesen Server stattdessen als Remote-MCP-Server zu betreiben.

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

[Fortgeschritten] Von überall erreichbar machen

Alles oben Genannte macht den Server nur vom selben Rechner aus erreichbar, auf dem er läuft. Es ist auch möglich, diesen Server stattdessen in der Cloud zu betreiben, mit aktivierter Authentifizierung – so ist er von überall erreichbar und nützlich für KI-Apps, die nur die Verbindung zu Remote-MCP-Servern über das Internet unterstützen.

Eine ausführliche Schritt-für-Schritt-Anleitung für eine Möglichkeit (Google Cloud Run mit Zugriffskontrolle über Google-Konten) finden Sie in .agents/skills/cloud-run-deploy/.

Dies erfordert etwas Vertrautheit mit Cloud- und Sicherheitskonzepten – Authentifizierung, Zugriffskontrolle und die laufenden Kosten eines öffentlich erreichbaren Servers. Es liegt in Ihrer Verantwortung, sicher zu operieren – betrachten Sie die Anleitung als Ausgangspunkt, den Sie anpassen sollten.

Architektur

• src/pipeline.py

  • Der Kern dieses Servers (GoogleMapsPipeline): sucht Bewertungen, ruft sie als CSV ab und gibt JSON mit der Bewertungsanalyse aus.

  • Die Suchlogik selbst basiert auf google-maps-scraper

• src/server.py

  • Der Einstiegspunkt für den MCP-Server (FastMCP).

So fließt eine Anfrage durch den Server

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

Entwicklungswerkzeuge

• tools/cli.py: ein leichtgewichtiger Client, um die Kernfunktion (GoogleMapsPipeline) direkt zu testen

• CLAUDE.md: das Handbuch für Coding-Agenten wie Claude Code

• .agents/skills/: wiederverwendbare Fähigkeiten für Coding-Agenten, die bei Entwicklung und Bereitstellung helfen

Lizenz

MIT