place-ratings-analyzer

日本語版: README_ja.md

An MCP server that fetches and analyzes Google Maps review ratings — not just the average star rating, but the full count breakdown across ★1–★5. Use it together with an AI app such as Claude Desktop.

What is this tool for?

AI apps such as Claude Desktop can already show you a restaurant's reputation as a number — a "★4.0 average." But that number alone can't tell you whether ratings cluster around ★4, or split between ★5 and ★1. This server looks up a place's reviews on Google Maps and gets the actual star-by-star breakdown, then gives you an assessment based on that pattern. Connect this server to your AI app, and it can investigate more deeply for you — checking a specific place's reputation, or finding places where ratings are split.

Installation

Installing this server takes a bit of computer know-how. If anything below is unclear, try showing this file to an AI app and asking it questions, or consider using an agentic feature like Cowork to handle the installation for you.

Requirements

• This server runs on Docker.
  • On Windows, Docker needs WSL. If you don't have it yet, open PowerShell (or a similar terminal) as Administrator and run:
    • wsl --install
  • This installs WSL and everything else you need in one step. Once it's done, restart Windows.
  • After restarting, open "Ubuntu" from the Start menu. The first launch will ask you to create a Linux username and password — pick whatever you like.
• There are two ways to install Docker itself:
  1. Install Docker Desktop.
     • This is the easier route.
     • If you're using it commercially (e.g. at a company), check your license terms — some situations require a paid plan.
  2. Install it from the command line on Ubuntu or another Linux environment.
     • Unlike Docker Desktop, this is free for commercial use too. Run:
     • sudo apt install -y docker.io
     • Depending on your environment, you may need extra setup beyond this command (e.g. adding Docker's own apt repository). See the web or Docker's documentation for details.

Downloading the repository

• Download it either with git clone, or as a ZIP file from this repository's page.
• To clone every file correctly on Windows, turn on Windows Developer Mode and add this option to git clone:
  • -c core.symlinks=true
  • Without it, a few of the project's developer-facing features (Agent Skills) are limited — the server itself still runs fine.

Using it from Claude Desktop

Here's how to connect this MCP server to Claude Desktop, a generative-AI app.

First, open a terminal in the folder where you cloned this repository, and run the following command to build the Docker image.

docker build -t place-ratings-analyzer .

Once the build finishes, register this server in Claude Desktop's config file. The file lives at:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

If claude_desktop_config.json doesn't exist yet, or is empty, create it in a text editor and paste in exactly this, then save:

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

If the file already exists with other settings in it, add the following block right after the line that reads "mcpServers": {, without deleting anything already there:

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

If you installed Docker directly inside WSL (rather than Docker Desktop) on Windows, replace "command" and "args" above with:

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

Helping your AI app proactively use this tool

So that your AI app (e.g. Claude Desktop) proactively uses this MCP server, paste the following into a chat and ask it to save this to memory:

---
name: mcp-research-tooling
description: Local MCP tools for practical research tasks, including the place-ratings-analyzer
sources: [chat]
aliases: [place-ratings-analyzer]
---
- [stated] Uses local MCP tools for practical research tasks (e.g. identifying low-rated izakaya in the Shinjuku area)
- [stated] Wants default place-search/display tools (e.g. location-based search, map display) combined with place-ratings-analyzer when it adds value (e.g. plotting shortlisted candidates on a map for distance/location context) — but only as an addition, never as a substitute for place-ratings-analyzer's own workflow (e.g. area+category search should not replace the individual per-store queries used to surface low-rated candidates, since it biases toward well-known/high-rated results). The guiding principle: enhance the experience, never degrade the existing one.

After saving it, start a new chat — the tool becomes more likely to be used from that point on.

Updating

Pulling repository updates (e.g. git pull) doesn't change anything running — the server runs from the Docker image, not the repository files. Rebuild the image and restart Claude Desktop:

docker build -t place-ratings-analyzer .

[Advanced] [Under development] Running as a remote MCP server

MCP servers can talk to clients in two ways: over stdio (standard I/O), or over HTTP/HTTPS. The latter is what's called a remote MCP server.

Some AI apps only support connecting to remote MCP servers — but everything up to this point has only covered the stdio method.

Run the following Docker command to run this server as a remote MCP server instead.

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

Architecture

• src/pipeline.py
  • This server's core (GoogleMapsPipeline): searches for reviews, fetches them as CSV, and outputs JSON with the rating analysis attached
  • The search logic itself is built on google-maps-scraper
• src/server.py
  • The FastMCP server's entry point

How a request flows through the 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

Developer tools

• tools/cli.py: a lightweight client for smoke-testing the core (GoogleMapsPipeline) directly
• CLAUDE.md: the manual for coding agents such as Claude Code
• .agents/skills/: a set of Agent Skills covering development steps too detailed for CLAUDE.md
  • Mainly written for coding agents to read, but also documents some of the trouble encountered during development and how it was resolved — background that's useful for human developers too